Core Laravel Package

Product Decisions This Supports

• Build vs. buy for the whole API delivery layer. This is not a library that solves one problem; it is a bet on a metadata-driven approach for serialization, routing, validation wiring, pagination, filtering, content negotiation and OpenAPI generation. The decision to evaluate is "do we adopt a framework convention for our API surface, or do we keep hand-assembling controllers, resources, transformers and Swagger annotations?" — and that is a roadmapping decision, not a code-style decision.
• Time-to-first-endpoint as a delivery metric. The core value proposition ("a working, fully-featured web API in minutes") maps to a PM-owned metric: time from ticket to a documented, conformant endpoint. If your current cycle involves writing a controller, a request validator, a resource transformer, a pagination helper, and hand-maintained API docs, this package compresses that into resource metadata plus a state provider. Worth quantifying against your last two sprints before committing.
• Contract-first planning with consumers. OpenAPI v2/v3 (and now 3.2) is generated from the same metadata that serves the API, so the published contract cannot silently drift from behaviour. That unlocks concrete roadmap items: generating client SDKs, onboarding partner integrations, passing an internal or external API review board, and populating a developer portal — without a separate documentation-sync workstream.
• GraphQL as a reversible decision. The same resource definitions can expose both hypermedia REST and GraphQL. A PM can therefore ship REST now and open a GraphQL surface later without a second codebase or a re-architecture. This lowers the cost of deferring the GraphQL decision, which is where most API roadmaps stall.
• Content-negotiation format choice as configuration, not code. JSON-LD, Hydra, JSON:API, HAL, Problem Details and plain JSON are supported natively. Product can pick per surface — strict JSON:API for partners with a spec mandate, HAL or JSON-LD for semantic/linked-data consumers, plain JSON for a mobile client — and treat the format as a negotiation rather than a rewrite.
• Search and filtering as a feature surface, not boilerplate. The changelog shows an active, deliberate investment in first-class filters (comparison, start/end/word-start search, OR filters, free-text across multiple properties, Elasticsearch integration stabilised, dedicated upgrade codemods). That means "advanced filtering on the customer list" can be planned as a product increment rather than a bespoke query-building epic.
• Early positioning on AI/agent surfaces. MCP support is present but explicitly still @experimental. That is exactly the right shape for a PM: it is a spike, not a roadmap commitment. Useful for a discovery track ("expose our catalogue as tools to an internal assistant"), not for a customer-facing promise.
• Procurement and licensing hygiene. MIT, self-hostable, no per-seat or per-call licensing, no vendor contract to negotiate. The cost is engineering time and upgrade maintenance, not invoices — which makes the business case simpler to argue and the exit cheaper if it fails.

When to Consider This Package

Consider adoption when:

• You are on PHP and your domain is naturally resource-shaped (catalogue, users, orders, content, bookings) — the more your API looks like CRUD plus filters, the higher the return.
• You have or expect several consumers with different needs (web, mobile, partners, internal services), making contract stability and auto-generated OpenAPI genuinely valuable rather than decorative.
• You need standards conformance (JSON:API, HAL, JSON-LD, RFC 7807 problem details) that would otherwise be hand-rolled and hand-maintained.
• You want REST and GraphQL from one codebase, or want the option to add GraphQL later without a rewrite.
• The team already knows Symfony, or is a Laravel team willing to accept a Symfony-flavoured abstraction layer in exchange for the feature set.

Look elsewhere, or scope down, when:

• Version compatibility gates the decision. The 4.4 line requires Symfony ^7.4 || ^8.0 and drops 6.4 and 7.0–7.3. If the platform is on an older Symfony, the realistic answer is to pin to 4.3.x, and the PM should plan an upgrade track rather than assume latest.
• You are a Laravel-only shop with no appetite for experiment risk. Laravel support was recently promoted out of @experimental, but the documentation, examples and community mindshare remain Symfony-first. Treat a Laravel adoption as a timeboxed prototype with an explicit go/no-go, not a foregone conclusion.
• The API is small or non-resource-shaped. A handful of endpoints, RPC-style actions, streaming, WebSockets, gRPC, or heavy file pipelines are poor fits; the framework's conventions become friction you pay for without collecting the benefit.
• The domain logic dominates the transport. If endpoints are thin wrappers over complex orchestration with no meaningful entity model, the metadata layer adds indirection without removing much code.
• Upgrade bandwidth is genuinely absent. The changelog is dense with deprecations and breaking changes across a 4.4 line and an in-flight 5.0. Codemods and upgrade guides mitigate this, but a PM must budget maintenance each cycle. A team that historically lets dependencies rot should not adopt a fast-moving framework.
• Verification caveat worth closing before you commit a quarter to it. The listed dependents: 0 conflicts with the package's apparent ecosystem role — likely an artefact of consumption via umbrella/metapackage or Flex rather than direct requires. Have engineering confirm real-world adoption and your own integration path before citing traction in a business case.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can deliver a standards-compliant, documented API in a fraction of the current effort by adopting an established MIT-licensed PHP framework instead of building the plumbing ourselves. It generates the OpenAPI contract from the same source of truth that serves the API, so documentation cannot drift, and it lets us expose REST now and GraphQL later without a second codebase. There is no licence cost — the investment is engineering time plus a maintenance cadence — and the main risk we are accepting is that the project moves quickly and expects periodic upgrades.

For engineering (the merits): A resource metadata layer with composable state providers and processors; first-class filters, pagination and validation integration; native serialization for JSON-LD/Hydra, JSON:API, HAL, Problem Details and OpenAPI 2/3/3.2; GraphQL and Elasticsearch support; DI-based extension points so anything can be overridden rather than forked; an upgrade codemod (api:upgrade-filter) to soften the filter-API migration. It is a framework commitment, not a drop-in helper — size it as such.

Risks to state plainly:

• Upgrade treadmill. Active deprecations plus a 5.0 in alpha. Mitigation: pin a minor, schedule an upgrade slot each cycle, adopt codemods early.
• Symfony-centricity. Highest-value path is the Symfony bundle; Laravel integration is newer. Mitigation: prototype on Laravel before committing, and keep the resource/state layer thin so an exit is possible.
• Convention over explicitness. Faster to build, slower to debug for engineers unfamiliar with the metadata model. Mitigation: budget a learning ramp and one internal reference implementation.
• Experimental features on the roadmap. MCP and some integrations carry stability caveats. Mitigation: keep them in discovery, out of committed scope, until promoted.