Gesso Laravel Package

Technical Evaluation

Scope of this release: v2.7.0 is a minor release (no BREAKING CHANGE footer) delivering 12 features and 7 fixes across configuration, adapters, CLI, validation, and CI integration. Gesso presents as a spec/contract-testing toolkit for PHP — OpenAPI-driven request/response validation, HTTP client fakes for consumer-side contract tests, route parity checks for Laravel, and coverage merge/gate commands — wired into PHPUnit/Pest via an extension and into Laravel via a service provider. Verdict: adopt/upgrade, but stage the two behavior-tightening changes separately from the config migration.

Architecture fit

• The package occupies the dev-tooling and CI layer rather than the application runtime. If that holds for your usage, blast radius is confined to developer workflow and pipeline, not production traffic. This is the single most important fact to confirm before planning anything else.
• config: share configuration between phpunit and laravel (#593) is the architectural centerpiece. A single gesso.php consumed by both the PHPUnit extension and the Laravel package removes the classic drift failure where local runs and CI enforce different rules. This is a genuine structural improvement, not a convenience.
• laravel: read route-side parity exclusions and the spec list from config (#621) moves routing exclusions out of code and into declarative config. Good for auditability, but it deepens coupling to Laravel's router internals — the Laravel major-version support matrix becomes a first-order compatibility concern.
• adapters: default the symfony and psr-7 policy hooks from the shared configuration (#614) adopts inheritance over per-adapter declaration. Compositionally cleaner; operationally it introduces an implicit surface where an adapter picks up global policy hooks that were previously absent. Silent inheritance is the highest-value item to test explicitly.

Integration feasibility

• High. doctor: emit an equivalent gesso.php with --emit-config (#627) is effectively a migration tool: generate the new shared config from existing state rather than hand-authoring it. Combined with --format and --output-file on every subcommand (#620) and config-defaulted coverage:merge/coverage:gate (#626), this release is unusually well-set-up for incremental adoption.
• No mandatory code changes. The only code-level touch point is contract: move named contract checks to the Contract namespace behind a deprecated Fuzz alias (#608) — deprecation-only, no removal announced.

Technical risk: Low–Medium

• No declared breaking changes, but three changes are semantically breaking for consumers relying on previously lax behavior:
  • validation: decode adapter JSON bodies as objects so a nested {} is not read as [] (#561) — empty-object vs empty-array distinctions now matter. Contracts or fixtures that passed by conflating the two will start failing.
  • validation: honor form encoding style, explode, and part headers (#619) and validation: preserve body boundaries across adapters and doctor (#566) — stricter, more spec-faithful multipart handling. Correct, but it converts previously-tolerated spec looseness into red builds.
  • adapters policy-hook defaults (#614) — behavioral, and potentially affects any non-test code path that uses the adapters.
• Low-risk items: enum-drift once per paratest run (#613) is a pure CI-time win; phpunit: tolerate the sealed event facade in the pest --parallel orchestrator (#599) is a stability fix; config: lower-case setting values without ext-mbstring (#570) implies mbstring is optional and only affects non-ASCII setting values; docs advisory bumps (#601) are dev-only.

Key questions for the maintainers

1. Does Gesso ship any non-dev, production runtime code path — specifically, do the Symfony/PSR-7 adapters execute in production request handling? If yes, #614 is a runtime behavior change requiring a change-control review, not a dev-dep bump.
2. What is the documented precedence order between gesso.php, phpunit.xml, extension parameters, and CLI flags? #593 and #626 both introduce config-sourced defaults; ambiguity here produces local/CI divergence.
3. Is --emit-config lossless and idempotent — does it round-trip an existing phpunit.xml + extension setup without dropping settings?
4. Is the Fuzz alias removal scheduled for a specific major, and is there a deprecation-notice mechanism that will fail builds under strict error handling?
5. Does #561 change documented comparison semantics, and is there a migration note or opt-out flag for teams that intentionally used [] to mean "any empty"?
6. What are the supported Laravel and PHP floor versions, and does the PHPStan 2.3 pinning (#600) conflict with project- or monorepo-level analysis pins?

Integration Approach

Stack fit

• Natural fit for Laravel services with Pest or PHPUnit suites and an OpenAPI (or equivalent) spec artifact. It augments an existing pipeline rather than replacing it — no framework swap, no new runtime dependency if the dev-only assumption holds.
• Best value where multiple Laravel services need consistent contract enforcement: the shared-config model is what makes org-wide standardization tractable.

Migration path (config-first, additive)

1. Pin the currently deployed version; capture a green baseline on both serial and parallel runs.
2. Run gesso doctor --emit-config to generate a candidate gesso.php.
3. Diff the generated config against phpunit.xml and current extension parameters; reconcile deliberately, recording any setting that has no equivalent.
4. Enable shared config (#593) with validation behavior otherwise unchanged — this is the isolated step.
5. Separately, opt into the new validation fidelity (#561, #566, #619) and triage resulting failures as either spec defects or over-strict assertions.
6. Wire --format/--output-file (#620) into CI reporting so results are machine-readable.
7. Move coverage thresholds into config via coverage:merge/coverage:gate defaults (#626) only after confirming they reproduce current gate behavior exactly.
8. Defer the Contract namespace rename; keep the Fuzz alias and track its removal.

Compatibility checks before merge

• Pest parallel suites with event fakes — confirm #599 resolves rather than masks the sealed-facade issue in your Pest version.
• PHP versions without mbstring — verify #570 covers your setting values.
• Root composer.lock resolution against the newly pinned dev analysis tools (#600).

Sequencing caution: do not land the config unification and the validation-fidelity adoption in the same change. They are independent failure sources, and combining them makes triage of a red build materially harder.

Gate criteria: two consecutive green full runs (serial and parallel) on the new config, plus an exact match on prior coverage gate outcomes.

Operational Impact

Maintenance

• High release velocity: 19 discrete changes in one minor. Treat as a fast-moving dev dependency — pin exact versions, review release notes per bump rather than floating ranges.
• The Contract namespace deprecation creates a standing inventory item. Track every Fuzz\ reference in your codebase so the eventual alias removal is a scheduled cleanup, not an outage.
• Pinned dev analysis tools (#600) improve reproducibility but can conflict with monorepo-wide pins; check dependency resolution at the root, not just per-package.

Support

• Deprecation channel is being used correctly (alias + notice), which is a good maintenance signal.
• Expect support questions concentrated in two areas: "why did my tests start failing after upgrade" (validation tightening) and "which config wins" (precedence). Pre-empt both with an internal migration note.

Scaling

• enum-drift evaluated once per paratest run (#613) is a direct CI-time saving that compounds with suite size — quantify it during the pilot to build the case for broader rollout.
• Shared config materially reduces per-service onboarding cost. This is the strongest argument for standardizing across many Laravel services rather than adopting per-team.

Failure modes to watch

1. Silent policy inheritance on adapters (#614) causing over- or under-enforcement with no explicit signal.
2. Strict JSON object semantics (#561) presenting as intermittent, hard-to-attribute test failures.
3. Config precedence ambiguity producing green locally / red in CI, or the inverse.
4. Coverage gate misconfiguration blocking merges — validate the configured defaults reproduce current behavior before enabling.
5. --output-file artifacts being committed accidentally; add ignore rules up front.
6. Route parity exclusions now living in config (#621) drifting from the actual spec without review.

Rollback

• Config-only changes are cleanly reversible via version control. The sticky surface is contract assertion changes adopted under #561/#566/#619 — snapshot assertion output before and after so a rollback of the package version also restores expected results.

Ramp-up

• Low-to-moderate for developers: doctor plus --emit-config substantially shortens time-to-first-green.
• The validation fidelity work raises the bar on OpenAPI literacy. Budget review time for spec owners, not just application developers — the failures this release surfaces are frequently spec defects, and the people who can adjudicate them are often not the people running the tests.