NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #1745 most downloaded on Packagist
Testing helpers for your OpenAPI spec
Latest stable
v3.0.4
Last release 3 months ago
23 Aug 2026
Release timing varies
gaps range from 2 weeks to 12 months
Most releases are documented
notes for 50 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
68 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
Return stdClass for empty x-www-form-urlencoded request bodies (fixes 500 on empty form posts against object schemas) by @egretos in #223
stdClass for empty x-www-form-urlencoded request bodies (fixes 500 on empty form posts against object schemas) by @egretos in #223spectator:routes output by @jaap in #222Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.3...v3.0.4
Widen cebe/php-openapi constraint to ^1.7 so users can opt into the devizzent/cebe-php-openapi fork (Symfony 8 / PHP 8.5 compatibility) by @hotmeteor
cebe/php-openapi constraint to ^1.7 so users can opt into the devizzent/cebe-php-openapi fork (Symfony 8 / PHP 8.5 compatibility) by @hotmeteor in #225Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.2...v3.0.3
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Add --prefix and --middleware filters to spectator:routes by @jaap in https://github.com/hotmeteor/spectator/pull/221
Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.1...v3.0.2
Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.0...v3.0.1
Full Changelog: https://github.com/hotmeteor/spectator/compare/v3.0.0...v3.0.1
v3 is a significant release that raises the platform floor, adds a suite of developer-experience tools, and fixes several validation edge cases.
v3 is a significant release that raises the platform floor, adds a suite of developer-experience tools, and fixes several validation edge cases.
Minimum requirements
New config key
A new error_format key is required in config/spectator.php. If you published the config in v2, add:
'error_format' => env('SPECTATOR_ERROR_FORMAT', 'text'),
No behaviour change unless you set SPECTATOR_ERROR_FORMAT=json.
Internal type changes (extenders only)
If you extend Spectator's validator classes, note that:
'read' / 'write' strings in AbstractValidator are now ValidationMode::Read / ValidationMode::Write enum casesFormat::TEXT_GREEN style class constants are now Format::TextGreen string-backed enum casesThese are internal details — if you only use the public facade and TestResponse assertions, no action is required.
See UPGRADE.md for the full list.
Four new artisan commands provide visibility into your spec and its relationship to your application.
spectator:validate — lint a spec file before tests run:
php artisan spectator:validate --spec=Api.v1.yml
php artisan spectator:validate --spec=Api.v1.yml --format=json
spectator:coverage — list every operation defined in the spec:
php artisan spectator:coverage --spec=Api.v1.yml
spectator:routes — cross-reference spec operations against your registered Laravel routes:
php artisan spectator:routes --spec=Api.v1.yml
Outputs matched, unimplemented, and undocumented routes at a glance.
spectator:stubs — generate skeleton test classes from a spec, ready to fill in:
php artisan spectator:stubs --spec=Api.v1.yml --output=tests/Contract
Operations are grouped by tag (falling back to path segment), producing one test class per group with one markTestIncomplete method per operation.
All commands support --format=json for machine-readable output.
SpectatorExtension is a PHPUnit 11 extension that tracks which spec operations are exercised across the full test run and prints a summary table when the suite finishes. Configure a minimum threshold to fail CI when coverage drops:
<extensions>
<bootstrap class="Spectator\Coverage\SpectatorExtension">
<parameter name="min_coverage" value="80"/>
</bootstrap>
</extensions>
Validation errors can now be emitted as structured JSON instead of ANSI-coloured text — useful for CI log parsers, LLM-driven workflows, and anything that processes test output programmatically:
SPECTATOR_ERROR_FORMAT=json
Or toggle per test:
Spectator::useJsonErrors();
Spectator::useTextErrors();
A failed assertion with JSON errors produces:
{ "errors": ["The data (null) must match the type: string"] }
Spectator::withPathPrefix('v1');
As an alternative to setting SPECTATOR_PATH_PREFIX in .env.
The combination of spectator:validate --format=json, SPECTATOR_ERROR_FORMAT=json, and SpectatorExtension makes Spectator a natural fit for AI-driven development workflows — structured outputs at every stage mean errors and coverage gaps can be piped directly into LLM toolchains.
Nullable inside additionalProperties not migrated — OpenAPI 3.0 nullable: true on dictionary value schemas was silently skipped during the 3.0 to 3.1 nullable migration. Values like null were incorrectly rejected. (#215)
Comma-separated values in header parameters — explode: false with type: array on in: header parameters now correctly splits the comma-separated string into an array before validation, matching the existing behaviour for query parameters. (inspired by #213)
TypeError with empty request body on allOf schemas — sending an empty body against a required allOf request body no longer throws a TypeError. The error is now a clean "Request body required!" validation failure. (#216)
Nullable properties inside allOf — nullable: true on properties nested within allOf arms is correctly migrated to 3.1-style type: [T, null]. (#212)
ValidationMode, Format, Source)readonly properties, and match expressions used where appropriatehttps://github.com/hotmeteor/spectator/compare/v2.5.2...v3.0.0
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.2.1...v2.3.0
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.2.1...v2.3.0
Fix: objects without properties, and arrays without items by @philsturgeon in https://github.com/hotmeteor/spectator/pull/219
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.2.0...v2.2.1
Laravel future proofing by @hotmeteor in https://github.com/hotmeteor/spectator/pull/218
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.1.2...v2.2.0
Run tests on PHP 8.4 by @bastien-phi in https://github.com/hotmeteor/spectator/pull/205
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.1.1...v2.1.2
cachedSpecs is initialized every time. by @hirotaka056 in https://github.com/hotmeteor/spectator/pull/209
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.1.0...v2.1.1
fix: Update _ide_helpers.php by @villfa in https://github.com/hotmeteor/spectator/pull/199
Full Changelog: https://github.com/hotmeteor/spectator/compare/v2.0...v2.1.0
Update by @hotmeteor in https://github.com/hotmeteor/spectator/pull/134
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.9.0...v1.11.0
Fix undefined variable $response in Middleware by @bastien-phi in https://github.com/hotmeteor/spectator/pull/137
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.9.1...v1.10.0
Handle validation of nested query parameters e.g. ?filter[groupId]= by @HughbertD in https://github.com/hotmeteor/spectator/pull/129
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.7.0...v1.9.1
Add ability to choose which groups the middleware should be prepended to by @cmseguin in https://github.com/hotmeteor/spectator/pull/148
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.8.0...v1.9.0
Laravel 10.x Compatibility by @johnathanmdell in https://github.com/hotmeteor/spectator/pull/141
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.7.1...v1.8.0
Handle validation of nested query parameters e.g. ?filter[groupId]= by @HughbertD in https://github.com/hotmeteor/spectator/pull/129
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.7.0...v1.7.1
Fix example snippet syntax by @andrew-demb in https://github.com/hotmeteor/spectator/pull/122
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.6.0.1...v1.7.0
Cache exceptions for selective reporting by @hotmeteor in https://github.com/hotmeteor/spectator/pull/110
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.5.1...v1.6.0
Add support for nullable objects as properties and various anyOf usages by @DeepDiver1975 in https://github.com/hotmeteor/spectator/pull/108
$path param by @pH-7 in https://github.com/hotmeteor/spectator/pull/105Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.5.0...v1.5.1
Add Laravel 9 support, drop Laravel 7 support by @bastien-phi in https://github.com/hotmeteor/spectator/pull/98
Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.4.1...v1.5.0
Parameter type check and casting by @SudoGetBeer in https://github.com/hotmeteor/spectator/pull/89
formatSchema function does not return array by @jransijn in https://github.com/hotmeteor/spectator/pull/83Full Changelog: https://github.com/hotmeteor/spectator/compare/v1.4.0...v1.4.1
Greatly improved error message display
Add support for oneOf and anyOf
Nothing published for this version
Nothing published for this version
The Spectator middleware will now be prepended to the middleware stack vs appended so that models are not bound, and specs can match on primitive type
The Spectator middleware will now be prepended to the middleware stack vs appended so that models are not bound, and specs can match on primitive types.
This release fixes the parsing of route parameters.
This release fixes the parsing of route parameters.
Nothing published for this version
Error rendering has been greatly improved so that now all validation issues are displayed:
Error rendering has been greatly improved so that now all validation issues are displayed:
Improves support for path_prefix config value
path_prefix config value->setPathPrefix($prefix) inline support for ad hoc pathsFixed issue where spec paths weren't being reconciled properly
->getErrors() methodNothing published for this version
Nothing published for this version
Fixes parsing of component references that aren't being resolved correctly by https://github.com/cebe/php-openapi/issues/31
Fixes parsing of component references that aren't being resolved correctly by https://github.com/cebe/php-openapi/issues/31
Upgrade opis/json-schema to ^2.0
opis/json-schema to ^2.0opis/json-schema:^2.0uses keyword in the JSON-ified message, it's now typeWill now provide informative feedback if the spec file being used is malformed and needs linting
$this->withoutExceptionHandling() in your test case (https://github.com/hotmeteor/spectator/pull/34) (from @beblife)Refs https://github.com/hotmeteor/spectator/pull/25
Refs https://github.com/hotmeteor/spectator/pull/25
Refs https://github.com/hotmeteor/spectator/pull/27
Refs https://github.com/hotmeteor/spectator/pull/27
Nothing published for this version
https://github.com/hotmeteor/spectator/pull/24
https://github.com/hotmeteor/spectator/pull/24
Removes support for PHP 7.2 and Laravel 6
Removes support for PHP 7.2 and Laravel 6
Enforces Laravel 7 min version of 7.30.3
Enforces Laravel 7 min version of 7.30.3
Doesn't apply to 3.1.x specs since nullable will be deprecated
Assertions class (https://github.com/hotmeteor/spectator/pull/21)nullable property by forcing an array of types that include null (https://github.com/hotmeteor/spectator/pull/20)
nullable will be deprecatedResponseValidator to be more readableYet another service provider and config fix.
Yet another service provider and config fix.
Fixes issue with bad service provider reference in composer.json
Fixes issue with bad service provider reference in composer.json (https://github.com/hotmeteor/spectator/pull/14)
Updates some class naming for clarity
_ide_helper.php for better intellisense supportAllow for multiple path parts using path_prefix config.
Allow for multiple path parts using path_prefix config.
Fix issue where prefix wasn't probably being mapped to paths.
Fix issue where prefix wasn't probably being mapped to paths.
Added new path_prefix config option
path_prefix config option
path_prefix in Spectator configAdds support for JSON:API content type
.yml files (https://github.com/hotmeteor/spectator/pull/8)operationId not defined (https://github.com/hotmeteor/spectator/pull/4)Nothing published for this version
Nothing published for this version
Improves the test error message when there are invalid schema keywords.
Improves the test error message when there are invalid schema keywords.
Nothing published for this version
This release uses a new JSON schema validator, swapping https://github.com/justinrainbow/json-schema out for https://github.com/opis/json-schema. The
This release uses a new JSON schema validator, swapping https://github.com/justinrainbow/json-schema out for https://github.com/opis/json-schema. The latter has better documentation and more descriptive error message support.
Updates dependencies to support Laravel 8 apps.
Updates dependencies to support Laravel 8 apps.
Nothing published for this version
Adds support for remote sources
The Middleware no longer leverages the router to handle path parsing, which was breaking on implicit route binding. Also properly reports response err
The Middleware no longer leverages the router to handle path parsing, which was breaking on implicit route binding. Also properly reports response errors.
One column per quarter.