Gesso Laravel Package

Product Decisions This Supports

• Build vs. buy for contract testing. Gesso already covers the build surface most teams would otherwise hand-roll: spec-to-route parity, response validation, HTTP client fakes, coverage gating, and CI reporting. The v2.7.0 work is almost entirely about reducing the glue code you'd write yourself, which strengthens the "buy/adopt" case.
• Whether API contracts become a merge gate. coverage:merge and coverage:gate now default from gesso.php via --config, so contract coverage can be enforced in CI with configuration instead of bespoke pipeline scripts. This is a policy decision: is contract parity a hard requirement or a report-only signal?
• API versioning and deprecation policy. Enum drift detection evaluated once per paratest run, plus named contract checks moving to the Contract namespace, gives you a repeatable signal for schema evolution. That supports decisions about when a change is additive vs. breaking, and how long deprecation windows run.
• Scope of the contract layer: Laravel-only or shared across PHP services. Adapters for Symfony and PSR-7, now defaulting their policy hooks from shared configuration, plus shared config between PHPUnit and Laravel, mean a single contract definition can serve multiple runtimes. This directly informs whether you standardize contract testing across the PHP estate or keep it inside one Laravel app.
• Consumer-side vs. provider-side testing investment. Spec-driven HTTP client fakes for contract testing make it cheaper to test consumers against the spec rather than against live providers. That supports decisions about test-environment dependency, flaky integration suites, and whether to fund a service-virtualization effort.
• Developer experience and onboarding budget. doctor --emit-config generates an equivalent gesso.php, and config now drives route-side parity exclusions and the spec list. This lowers the cost of adoption and migration, and supports a decision to standardize tooling rather than per-team configuration.
• Observability of quality metrics. --format and --output-file on every subcommand means contract results can be exported into dashboards or PR annotations without custom wrappers, supporting a decision to publish API quality metrics to stakeholders.
• Correctness decisions in the API surface itself. Honoring form encoding style, explode, and part headers, and preserving body boundaries across adapters, means multipart/form-encoded endpoints are now testable. This supports decisions about whether to accept file upload or form-heavy endpoints into the contract-tested surface.

When to Consider This Package

Consider adopting when:

• You maintain a machine-readable API spec (OpenAPI or equivalent) and it is drifting from the implementation, or drift is caught late in QA.
• The application is Laravel, Symfony, or PSR-7 based, and you use PHPUnit or Pest as the test runner.
• You want contract parity enforced in CI as a gate rather than as a periodic audit, including coverage thresholds.
• You have multiple consumers of your API (frontends, mobile, partner integrations) and want consumer-side tests that run against the spec instead of a live service.
• You have form-encoded or multipart endpoints, file uploads, or nested JSON payloads that are currently under-tested.
• You need one configuration to cover both the test runner and the framework integration, and you want a supported path to migrate existing config.

Look elsewhere or defer when:

• There is no formal spec and no appetite to own one; the package's value is proportional to spec quality.
• The stack is not PHP, or the API is predominantly GraphQL or gRPC without an OpenAPI layer — the adapters are PHP-centric.
• The API surface is small and stable enough that a handful of smoke tests provides equivalent risk coverage.
• You need a hosted dashboard or SaaS reporting product; this is a library plus CLI, and reporting is file-based.
• The team relies on mocked HTTP layers rather than real client abstractions and is not prepared to reshape that.
• You cannot absorb the deprecation path from the Fuzz alias to the Contract namespace, or you pin dev analysis tooling and cannot take the PHPStan-related upgrades.

Note that this is a minor release: features are additive and the one namespace move is aliased as deprecated, so adoption risk is low, but the deprecation should be scheduled rather than ignored.

How to Pitch It (Stakeholders)

For executives. This package makes API contracts enforceable in CI instead of aspirational in a document. The practical effect is that breaking changes to request/response shapes, enum values, and form encodings are caught in the pull request rather than by a partner or a customer. v2.7.0 strengthens that by making contract coverage a configurable gate, exporting results in standard formats for reporting, and adding a self-diagnostic that generates a working config file. The commercial argument is reduced integration incidents and less manual QA on API changes; the cost is a modest one-time investment in owning the spec and a small configuration change.

For engineering leadership. Adoption is low-friction for a Laravel, Symfony, or PSR-7 codebase on PHPUnit or Pest. Configuration is now shared between the test runner and the framework integration, the spec list and route-side parity exclusions are read from config, and doctor --emit-config produces an equivalent gesso.php from an existing setup, which de-risks migration. Contract checks have moved to a Contract namespace with the old Fuzz alias kept as deprecated, so there is a clear, non-urgent migration path. Adapters for Symfony and PSR-7 now inherit policy hooks from shared configuration, which means multi-service PHP estates can standardize on one contract definition. Consumer-side contract testing is supported through spec-driven HTTP client fakes, reducing dependence on live integration environments.

For the engineering team. Every CLI subcommand now accepts --format and --output-file, so results can be piped into CI annotations or dashboards without wrapper scripts. coverage:merge and coverage:gate read defaults from gesso.php via --config. Enum drift is evaluated once per paratest run rather than per worker, which removes a source of duplicated work in parallel suites. Validation now honors form encoding style, explode, and part headers, and body boundaries are preserved across adapters and the doctor command — this is the fix that makes multipart and file-upload endpoints genuinely testable. JSON bodies are decoded as objects so a nested {} is no longer misread as [], and config values are normalized consistently between gesso.php and extension parameters, including without ext-mbstring. Dev analysis tooling is pinned to keep PHPStan 2.3 findings stable — budget a small maintenance window if you track those pins.