Php Openapi Laravel Package

Product Decisions This Supports

• API-first / contract-as-code strategy. If we want the OpenAPI document to be the source of truth rather than a doc artifact generated after the fact, something has to read that document programmatically inside PHP. This package is that primitive — everything else (docs, tests, codegen) sits on top of it.
• Documentation pipeline. Read the spec in an artisan command or CI job, walk paths, operations, components->schemas, and render docs, changelogs, or per-endpoint guides without hand-maintained duplication.
• CI quality gates. The bundled CLI gives us validate (exit code 2 on errors) and convert, so "spec must be valid before merge" becomes a pipeline step, not a review convention. Cheap, high-leverage governance.
• Contract testing. hotmeteor/spectator and league/openapi-psr7-validator both build on this library — meaning we can validate real Laravel test requests/responses against the spec. This is the decision that most directly reduces integration defects.
• Code generation and scaffolding. Generate routes, controllers, form requests, DTOs, and fake data from the spec. cebe/yii2-openapi is the reference implementation of that pattern; we'd port the idea, not the code.
• Spec as configuration. Drive gateway/ingress rules, route registration, SDK stubs, or Postman collections from one artifact. convert/inline (external-ref inlining into a single file) is the unglamorous but genuinely useful piece here.
• Breaking-change detection. Read two spec versions, diff operations and schemas, fail the build. This is a roadmap item most teams defer precisely because "we'd have to parse OpenAPI ourselves."
• Build vs buy. The alternative is writing a YAML/JSON parser plus an object model for ~40 spec types plus reference resolution. That is weeks of undifferentiated work with a long tail of edge cases. Buying here is clearly correct; the only real question is which package.

When to Consider This Package

Adopt when:

• We are on PHP 7.1+ / Laravel, and the spec is OpenAPI 3.0.x. That's the supported surface, and it's stated plainly.
• We need programmatic read and write access — manipulating or generating specs, not just rendering them. This is where the library is strongest: the object model mirrors the spec 1:1, so $openapi->components->schemas['Foo']->properties['message'] works as expected.
• We have multi-file specs with $ref and need resolution. The RESOLVE_MODE_INLINE vs RESOLVE_MODE_ALL distinction and recursive-reference handling are real engineering that we should not rebuild. Relative-path resolution was actively fixed through 1.8.0.
• We want a CLI in CI with a sane exit-code contract.
• We're building internal tooling, not request-path runtime behavior. This is a low-level library for higher-level tools; treat it as an internal dependency.

Look elsewhere when:

• OpenAPI 3.1 is required. This is 3.0.x only. If our roadmap commits to 3.1 (JSON Schema 2020-12 alignment, webhooks, type arrays), this package does not get us there and the migration cost lands on us later. Decide this before adoption, not after.
• We need rigorous Schema Object validation. The README is explicit: validate() is basic and incomplete, and Schema Object validation is unchecked. Full JSON-Schema validation exists only in the CLI. If validation depth is a requirement, we need a second tool in the pipeline.
• We want an opinionated framework integration. This is deliberately unopinionated. For a Laravel-native experience — annotations, auto-generated docs UI, request validation — we should evaluate dedoc/scramble, darkaonline/l5-swagger, or vyuldashev/laravel-openapi instead, and use this only if we outgrow them.
• Runtime request/response validation is the goal. That's league/openapi-psr7-validator, not this package directly.
• We need vendor accountability. Effectively single-maintainer, no commercial SLA behind the OSS (paid support exists but is a consulting arrangement). "Dependents: 0" in the registry snapshot understates reality — the README lists real downstream consumers — but the governance risk is genuine for anything load-bearing.

Bottom line on fit: a strong enabler, weak product. Score it as infrastructure, budget for it accordingly, and isolate it behind a thin internal wrapper so a 3.1 migration or a package swap is a contained change.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed PHP library that lets our code read and manipulate our API specification file directly. It is the cheapest possible way to unlock three things we currently do by hand: keeping documentation in sync with the API, automatically failing builds when the API contract breaks, and generating boilerplate code instead of writing it. Cost is a Composer dependency and a day of integration; the alternative is building and maintaining a parser ourselves. The risks are narrow and known: it supports OpenAPI 3.0 only (not 3.1), its built-in validation is shallow, and it is maintained by a very small team — so we adopt it for internal tooling and CI, and we don't put it on the request path.

To engineering: It's a well-factored low-level library, not a framework plugin. The object model maps one-to-one onto the OpenAPI 3.0 spec, so there's no abstraction to learn and no leaky query API to fight. Reference resolution — including external files, relative paths, and recursive pointers — is solved, and RESOLVE_MODE_INLINE lets us ship a single self-contained spec. It tracks modern PHP: releases target PHP 8.2/8.3, Symfony 7, and PHPStan 1.x, and 1.8.0 added getRawSpecData() for cases where we want the original document alongside the typed objects.

What we're explicitly accepting: 3.0.x only — treat any 3.1 requirement as a separate decision with its own cost. Validation is a structural smoke test, not a schema conformance check; if we need that, we pair it with a complementary validator and we don't pretend otherwise. Single-maintainer bus factor means we wrap it: one internal service class, no direct cebe\openapi\* imports scattered through the codebase, so replacement stays a contained refactor.

Recommendation: Adopt now, scoped to CI validation, spec-driven docs, and contract testing via spectator. Treat codegen and breaking-change detection as the next two increments once the spec is actually trustworthy. Revisit the 3.0-vs-3.1 question at the next planning cycle rather than deferring it indefinitely.