Laravel Openapi Validator Laravel Package

Product Decisions This Supports

• Making the OpenAPI spec an executable contract rather than an advisory document. This package lets you decide that the spec is authoritative: it validates inbound Laravel HTTP requests against an OpenAPI 3 document and returns familiar Laravel validation errors. That is a governance decision with real teeth — the spec becomes something the build verifies, not a PDF that drifts from reality.
• Shifting contract breakage detection left. The strongest PM framing is CI/feature-test integration: a developer who changes payloads, headers, query or path parameters without updating the spec gets a failing build before a partner, mobile client, or downstream service is affected. This maps directly onto roadmap themes like "reduce integration defects," "stabilize partner integrations," or "improve API reliability" — and gives you a defensible metric (escaped contract defects per release) rather than a vague quality claim.
• Build vs. buy on request validation. Teams routinely hand-write Laravel FormRequest rules that duplicate what the OpenAPI spec already declares, then let the two drift. This package replaces duplicated validation with spec-driven checks. The "buy" case is strong only where a maintained spec already exists; otherwise the real project is spec authoring with the package as a downstream benefit.
• Reducing documentation decay and support load. If support or solutions engineering regularly reconciles "the docs said X but the API does Y," this turns silent drift into a loud CI failure. That is a measurable reduction in a recurring, low-glamour support cost — the kind of thing that is easy to fund once quantified.
• Sequencing a low-risk, incremental rollout. Product can choose test-suite validation first, shadow-mode middleware second (validate and log, never reject), and enforcing middleware third, route group by route group. That converts a platform-wide-sounding initiative into a bounded pilot with a rollback that does not require a deploy.
• Separating decisions that are easy to bundle by accident. Request-only vs. response validation, and test-time vs. production enforcement, carry very different false-positive and CPU cost profiles. This package supports both, which means PM should explicitly scope them apart rather than accepting the default bundle.
• A maintenance-posture signal for dependency risk. Release 2.0.2 is a compatibility bump widening the accepted constraint for symfony/psr-http-message-bridge to v8, with no behavioral change. For a build-vs-buy call that is useful evidence the package is kept current with Laravel/Symfony upgrades — it defuses the "this will block our framework upgrade" objection.
• Honest adoption reality check. 58 stars, 0 dependents, single-vendor maintenance. Treat it as a narrow, MIT-licensed, replaceable adapter — thin enough to fork, vendor, or drop. Appropriate as a validation helper; not appropriate as load-bearing tier-1 infrastructure without a stated exit plan.

When to Consider This Package

Consider it when:

• You already maintain a reasonably complete OpenAPI 3 spec for at least one API. Without that, the value proposition collapses into "write an OpenAPI spec" — a content-ownership project, not a middleware ticket.
• Your stack is Laravel/PHP and you want contract validation inside the existing PHPUnit/Pest suite rather than standing up a separate contract-testing toolchain or language.
• You want spec/code drift caught on every pull request with no new CI service to operate or pay for.
• Your API surface is growing or has multiple consumers — mobile, partners, internal services — where an unannounced contract change is expensive and visible.
• You want a narrow, reversible dependency: MIT-licensed, thin adapter, scoped to specific route groups, easy to remove.
• You need confirmation of Symfony-era compatibility for an upgrade path; 2.0.2 accommodates bridge v8. Pin 2.0.2 explicitly rather than floating ^2.0.

Look elsewhere or proceed cautiously when:

• There is no spec, or a stale one. Budget spec authoring and ongoing ownership with a named owner, or the initiative dies in false-positive triage. This is the single most common failure mode.
• You need full API lifecycle tooling. This validates requests against a spec; it does not generate SDKs, run a mock server, lint specs, or produce documentation. Pair it with a linter/generator rather than expecting one tool to do everything.
• You plan throughput-sensitive production enforcement. Middleware validation adds per-request cost that scales with spec size and $ref/oneOf depth — the engine adapts Laravel → PSR-7 → validate → back. Benchmark first, or scope to tests plus non-production shadow mode.
• Response validation is the primary goal. It materially raises false-positive exposure and CPU cost; decide deliberately whether it is in scope at all, and if so, later.
• You need vendor SLAs or enterprise support. With 0 dependents and 58 stars you are effectively self-supporting; abandonment over a multi-year horizon is plausible.
• You have a single small, stable API. A handful of FormRequests is simpler, dependency-free, and demands no spec discipline.
• Dependency resolution is fragile. Bridge v8 tracks Symfony 8 and can lift the PHP floor. Pin the version and verify resolution in CI rather than assuming the bump is inert.

How to Pitch It (Stakeholders)

For executives: We can make our API documentation enforceable. This package checks Laravel requests against our OpenAPI spec automatically, so when code and documentation disagree, our test suite fails before a client is affected. The return is fewer integration bugs and less engineering and support time spent reconciling "what the docs say" with "what the API does," at the cost of a small, MIT-licensed dependency and the discipline of maintaining the spec. It is a modest, reversible investment rather than a platform commitment — the package is thin and easy to remove, and rollout is route group by route group with a switch that does not require a deploy. The latest release, 2.0.2, is a maintenance-only compatibility update, which is the signal we want: the project is being kept current with the framework ecosystem rather than abandoned mid-upgrade. The main non-engineering cost is ownership of the spec itself; without a named owner, this delivers nothing. Realistic ask: roughly one to two engineer-days of wiring for a pilot, plus ongoing spec stewardship.

For engineering: Use it in the HTTP test suite first, not in the request pipeline. Add the validation trait to one existing feature test against one endpoint, get it green, and learn the package's edge cases — content-type handling, $ref resolution, nullable/enum strictness — with near-zero blast radius. If it proves out, extend to route groups and consider shadow mode: validate and log, do not reject, for two to four weeks, comparing logged violations against real traffic before flipping any route group to enforcing behind a feature flag. Be deliberate up front about three things: whether response validation is in scope, what the error envelope looks like when validation rejects (this is API governance, not a config default — consumers' error handling depends on it), and whether an unloadable or unparseable spec fails open with loud alerting (recommended for the pilot) or closed. Expect false-positive triage to be the schedule risk, and expect nearly all false positives to be spec defects rather than code defects — so spec changes need review and versioning like code, or the middleware gets switched off within a quarter. Pin 2.0.2 and add a Composer resolution check to CI so a routine update cannot silently move the PSR-7 bridge to v8 and shift the PHP floor. Finally, be honest about dependency scale: 58 stars, 0 dependents, single-vendor maintenance. That is fine for a helper we can vendor or fork and replace — the exit plan is a fork, not a re-platform — but not something to build tier-1 enforcement on without one.