Prepare for Gesso 3.0
Gesso 3.0 removes the configuration keys, CLI spellings, and APIs that v2 deprecated. Upgrade to the latest v2.x first: every removal emits a [Gesso deprecation] notice there, so a clean run on it is a clean v3 upgrade. The per-surface ledger lives in UPGRADING.md. The PHP renames and removals below can be rewritten with the Rector set GessoSetList::V3.
Then require 3.0, which ships that Rector set. While it is in beta, the constraint needs the @beta flag:
composer require --dev "studio-design/gesso:^3.0@beta"Configuration
Since 3.0, gesso.php at the application root is the only configuration entry point.
- Generate it with
vendor/bin/gesso config:migrate --write. The command reads the PHPUnit extension's<parameter>elements and a published v2config/gesso.phpand writes the equivalentgesso.php. It also lists every other edit with its file and line: the parameters to delete, and the removed CLI flags and v2 environment variables incomposer.jsonscripts,.github/workflows/*.yml, andMakefile. In a Laravel application whoseconfig/gesso.phpcallsbase_path()or another helper, runphp artisan gesso:config-migrate --writeinstead. See config:migrate. - Delete the extension's
<parameter>elements (keep onlyconfig, and only for a non-default location). The full mapping table is inUPGRADING.md. To start from scratch instead, runvendor/bin/gesso doctor --spec=openapi/front.json --emit-config > gesso.phporphp artisan vendor:publish --tag=gesso. - Delete
config/gesso.php, renameconfig('gesso.auto_assert')-style lookups and overrides in tests to the new paths (config('gesso.laravel.auto_assert')), and runphp artisan config:clear. - Add
vendor/bin/gesso config:migrate --checkto CI until it exits0. Anenv()call inconfig/gesso.phpis written as its current value, with a warning. Re-wrap such values by hand, for example asgetenv('X') ?: 'default'.
A leftover parameter or flat key fails the run naming its replacement, so an incomplete migration cannot pass silently. See Configuration for every key.
CLI flags and exit codes
Each removed spelling is now a usage error (exit 2) whose message names the replacement, for example Unknown argument(s): --specs (removed in Gesso 3.0; use --spec-name).
| Command | Removed in 3.0 | Use instead |
|---|---|---|
coverage:merge | --specs=<a,b> | --spec-name=<name> (repeatable, comma-accepting) |
coverage:merge | --strip-prefixes=<a,b> | --strip-prefix=<prefix> (repeatable, comma-accepting) |
coverage:merge | --json-output=<path> | --report=json:<path> |
coverage:merge | --junit-output=<path> | --report=junit:<path> |
coverage:merge | --html-output=<path> | --report=html:<path> |
coverage:merge | --console-output=<mode> | --console-report=<mode> |
coverage:merge | --min-endpoint-coverage=<pct> | --min-coverage="endpoint=<pct>" |
coverage:merge | --min-response-coverage=<pct> | --min-coverage="response=<pct>" |
coverage:merge | --min-sdk-exercise-coverage=<pct> | --min-coverage="sdk_exercise=<pct>" |
coverage:merge | --min-coverage-strict | --min-coverage="strict" |
coverage:merge | --baseline-file=<path> | --baseline="violations=<path>" |
coverage:merge | --coverage-baseline-file=<path> | --baseline="coverage=<path>" |
coverage:merge | --coverage-baseline-stale=<mode> | --baseline-stale="coverage=<mode>" |
coverage:merge | --strict-required=<mode> | --strict-required="run=<mode>" |
coverage:merge | --strict-additional-properties=<mode> | --strict-additional-properties="run=<mode>" |
stubs, gesso:stubs | --output=<dir> | --output-dir=<dir> |
coverage:merge | exit 1 when a sidecar, report, or baseline file cannot be read or written | exit 2; a check for any non-zero exit needs no change |
coverage:merge | an unknown argument ignored with a [Gesso] WARNING | rejected with exit 2, as doctor, coverage:gate, and stubs already did |
A merge with several sink or threshold flags folds into one grouped flag: --min-endpoint-coverage=80 --min-coverage-strict becomes --min-coverage="endpoint=80,strict". See the CLI reference.
CLI JSON documents
Every JSON document Gesso emits names its version schema_version, as the validation, coverage, and Laravel route-parity documents already did. The --format=json output of doctor, coverage:gate, and stubs (and gesso:stubs) renamed schemaVersion to schema_version and moved to version 2. Their other fields are unchanged. The new explain and config:migrate documents start at schema_version: 1.
To migrate, read schema_version instead of schemaVersion in scripts and CI steps that parse these documents, and accept 2 where they check the value, for example jq -e '.schema_version == 2'. See the CLI reference.
Coverage sidecars
Gesso 3.0 merges only sidecars with envelopeVersion: 10, the envelope every worker has written since 2.7 (#505). The 2.x merge also read the legacy envelopes 2–9 (written by Gesso 1.9–2.6) and the bare coverage state with no envelopeVersion, with a [Gesso deprecation] notice since 2.9.0. The 3.0 merge rejects them, exiting 1 with a message that names the writing release and the fix:
[OpenAPI Coverage] FATAL: invalid sidecar payload: Sidecar envelope version 6
was written by a Gesso 1.9-2.6 worker; Gesso 3 reads envelopeVersion 10 only. …To migrate, install the same Gesso version in the worker and merge steps, delete any sidecar directory a v2 run left behind (for example, artifacts restored from an earlier CI run), and re-run the parallel suite. Old sidecars cannot be converted. See versioned sidecar compatibility.
Enum binding
Enums bind to the spec by component name only (#508). A backed enum matches the components.schemas entry named after its class (an Enum suffix on either side is ignored) in the configured specs. Keep #[BoundToOpenApiEnum] only for enums whose component has another name. These surfaces are gone:
- the file-path binding
#[BoundToOpenApiEnum('path/to/file.json')]and the attribute's$specPathproperty (deprecated in 2.8.0). The attribute now takes one required argument, the component name; its parameter is still calledcomponent. OpenApiSpecLoader::configure(enumBasePath:)andgetEnumBasePath()(deprecated in 2.8.0).EnumBindingException::forBinding()(deprecated in 2.7.0).- the
EnumBindingReasoncases that only file-path bindings raised (deprecated in 2.9.0):BasePathNotConfigured,EnumBasePathNotFound,EnumSpecBasePathOrphaned,SpecFileNotFound,MalformedJson,MalformedYaml,YamlLibraryMissing,NonMappingRoot, andEnumKeyMissing. These raised no notice, so search your code for the names, for example an arm of amatchoverEnumBindingReason.
// Before (v2)
#[BoundToOpenApiEnum('_shared/components/schemas/enums/IdpAuthorizeErrorCode.json')]
enum IdpErrorEnum: string { /* ... */ }
OpenApiSpecLoader::configure('openapi/bundled', enumBasePath: 'openapi');
EnumBindingException::forBinding($reason, $message, $enumFqcn);
// After (v3)
#[BoundToOpenApiEnum('IdpAuthorizeErrorCode')] // or no attribute when the names match
enum IdpErrorEnum: string { /* ... */ }
OpenApiSpecLoader::configure('openapi/bundled');
new EnumBindingException($reason, $message, $enumFqcn);Enum values are now read only from the documents OpenApiSpecLoader::load() returns. To keep per-enum source files, $ref them from components.schemas. A file path left in the attribute is read as a component name and fails as ComponentNotFound. The attribute with no argument fails as AttributeInvalid. See enum drift detection.
Assertion methods
The assertion methods of the Laravel, Symfony, and PSR-7 traits share three names: assertOpenApiResponse(), assertOpenApiRequest(), and assertOpenApiExchange() (deprecated in 2.10.0, which already has the new names). The response comes first; the request is optional.
| v2 | v3 |
|---|---|
Laravel assertResponseMatchesOpenApiSchema($response, ...) | assertOpenApiResponse($response, ...), now public |
Symfony assertResponseMatchesOpenApiSchema($request, $response, ...) | assertOpenApiResponse($response, $request, ...) |
Symfony assertRequestMatchesOpenApiSchema($request, ...) | assertOpenApiRequest($request, ...) |
Symfony assertClientMatchesOpenApiSchema($client, ...) | assertOpenApiExchange($client, ...) |
PSR-7 assertPsr7RequestMatchesOpenApiSchema($request, ...) | assertOpenApiRequest($request, ...) |
PSR-7 assertPsr7ResponseMatchesOpenApiSchema($request, $response) | assertOpenApiResponse($response, $request) |
PSR-7 assertPsr7ResponseForOperationMatchesOpenApiSchema($method, $path, $response) | assertOpenApiResponse($response, method: $method, path: $path) |
PSR-7 assertPsr7ExchangeMatchesOpenApiSchema($request, $response) | assertOpenApiExchange($request, $response) |
The Symfony assertOpenApiResponse() also takes method: and path: instead of a request.
// Before (v2)
$this->assertResponseMatchesOpenApiSchema($request, $response);
// After (v3)
$this->assertOpenApiResponse($response, $request);Server base paths
A request path now matches the base paths the spec's servers declare (ADR 0008). A request to /api/pets against servers: [{ url: "/api" }] and a /pets path matched nothing in v2 and validates in v3. The path as written is tried first, and a non-empty spec.strip_prefixes turns server base paths off, so a suite that already configures the prefix behaves as before. A test that expected the path-not-found failure must set spec.strip_prefixes or call a path the spec does not document.
Unquoted YAML dates
An unquoted date or date-time in a YAML spec is now a string, as it is in a JSON spec (#695). v2 handed validation the Unix timestamp symfony/yaml decodes it to, so enum: [2026-06-15] under format: date rejected the real value and doctor reported GSO314 for example: 2026-06-15.
The string is canonical, not the source text: 2026-06-15, or 2026-06-15T22:30:00 with the fraction and zone as written. A space separator becomes T, single-digit fields are padded, a date-time at midnight with no zone reads as a date, and an impossible day rolls over (2026-02-30 reads as 2026-03-02). Quote a value whose exact spelling matters. A test that relied on the integer must expect the string.
Mapping keys are not covered. A flow mapping with an unquoted date key ({2026-06-15: …}) no longer loads, and a block mapping key (2026-06-15:) is still the timestamp; quote the key in both.
405 responses need an Allow header
The unsupported_method contract check now fails a 405 that has no Allow header, as RFC 9110 requires, when the dispatcher returns a response object. A dispatcher that returns only the status code is checked as before. Laravel and Symfony set the header on their own 405 responses.
Contract-check aliases
The Studio\Gesso\Fuzz\ aliases of the named contract checks are gone (#503; deprecated in 2.7.0). ContractCheck, ContractCheckPlan, ContractCheckFailure, ContractCheckSkip, ContractCheckSummary, OpenApiContractChecks, and the @internal ContractCheckProbe resolve only under Studio\Gesso\Contract\. Generator types (ExploredCase, OpenApiSpecExplorer, ...) stay in Studio\Gesso\Fuzz\.
// Before (v2)
use Studio\Gesso\Fuzz\OpenApiContractChecks;
// After (v3)
use Studio\Gesso\Contract\OpenApiContractChecks;The v2 notice did not fire for an old name referenced after the class was already loaded, so search for Gesso\Fuzz\ContractCheck and Gesso\Fuzz\OpenApiContractChecks rather than relying on a silent v2.9 run.
PHPUnit dependency
phpunit/phpunit moved from Gesso's require to require-dev (#506; announced in 2.9.0), so installing Gesso no longer installs a test runner. Declare PHPUnit 12 or 13 in your own require-dev — a current 12.5+ or 13.x release. Gesso's ^12.0 || ^13.0 range is unchanged: PHPUnit 11 and Pest 3 stay unsupported, and a Composer conflict keeps them from being installed alongside Gesso.
composer require --dev "phpunit/phpunit:^12.5 || ^13.0"A Laravel 12 application still on PHPUnit 11 or Pest 3 must upgrade the runner first (for Pest, move to Pest 4):
composer require --dev "phpunit/phpunit:^12.5" --with-all-dependenciesGesso now declares ext-dom (JUnit coverage report) and ext-filter, which it used directly but had received through PHPUnit. Calling a Gesso assertion without PHPUnit installed throws a RuntimeException naming the composer require command instead of a "Class not found" fatal.
The private helpers composed into the assertion traits, deprecated in 2.9.0, are gone: failOpenApi() and assertOpenApi() (ValidatesOpenApiSchema, Symfony and PSR-7 OpenApiAssertions), failPsr7() and assertPsr7() (PSR-7 OpenApiAssertions), and failExplore() (ExploresOpenApiEndpoint).
// Before (v2)
$this->failOpenApi('message');
$this->assertOpenApi($condition, 'message');
// After (v3)
$this->fail('message');
$this->assertTrue($condition, 'message');Deprecated helper methods
OpenApiCoverageTracker::hasAnyCoverage() and the SkipOpenApiResolver trait's private shouldSkipOpenApi() (composed into ValidatesOpenApiSchema) are gone; both were deprecated in 2.7.0.
// Before (v2)
OpenApiCoverageTracker::hasAnyCoverage('front');
$this->shouldSkipOpenApi();
// After (v3)
OpenApiCoverageTracker::current()->hasAnyCoverageOn('front');
$this->findSkipOpenApiAttribute() !== null;ValidatesOpenApiSchema::resetValidatorCache() (@internal) and the trait's seven private static $cached* properties are gone too. They have done nothing since 2.7.0 moved the validator cache onto the test-case instance. Delete any self::resetValidatorCache() call from setUp() / tearDown().