Php Api Version Bundle Laravel Package

Product Decisions This Supports

• API lifecycle & versioning strategy — the package's core value is expressing API versions as a first-class, machine-readable concern (version negotiation on requests, plus deprecation/sunset signalling in responses). That directly backs roadmap decisions like "when do we cut v2," "how long do we keep v1 alive," and "how do we announce sunset to integrators."
• Build vs. buy for version negotiation — this is the cheapest credible answer to "we need versioning, do we write it ourselves?" A self-built version negotiator plus deprecation-header plumbing is typically 2–4 engineer-weeks including tests, plus permanent ownership. This package is a candidate to collapse that to a spike-sized integration.
• Public/partner API commitments — if the roadmap includes external consumers, contractual deprecation windows, or SLA language about version support, this provides the enforcement mechanism behind the promise rather than a wiki page nobody reads.
• Platform standardization — if multiple teams ship endpoints, a shared versioning convention (vs. each team inventing /v1/ vs. header vs. query-param) is a product-consistency decision. This package is the artifact that makes the convention enforceable in code review.
• Not supported: it is not an API gateway, not a contract-testing tool, not a developer-portal/changelog product, and not a substitute for OpenAPI governance. Do not let it absorb scope it doesn't own.

When to Consider This Package

Consider it when:

• You have multiple concurrently-live API versions (or know you will within two quarters) and no codified convention for negotiating them.
• You need deprecation and sunset semantics communicated in-band to clients, not just in release notes — i.e., you want machine-actionable signals so integrators can alert on them.
• You are on PHP 8.x / Composer and can absorb the integration cost; the package is a Composer library, so it composes into a Laravel app, but the ergonomics are Symfony-flavoured — expect framework glue work (service provider wiring, config publishing, middleware ordering) rather than a drop-in composer require experience.
• Your team is small and you'd rather own a convention than an implementation.
• You can accept 0.x semver — pre-1.03 releases can break in minors; pin exact versions and budget for periodic upgrade passes.

Look elsewhere (or build thin in-house) when:

• You need only a single URL-prefix scheme (/v1/, /v2/) — routing already does this; the package is overkill.
• You need versioning across non-PHP services — this is a PHP library, not a sidecar or gateway policy; a cross-language estate argues for an ingress-layer solution.
• You require vendor SLAs, security disclosure processes, or long-term support guarantees. This is a single-maintainer, low-velocity project (this release is dependency bumps only); treat it as "adopt with a fork-and-own plan," not "bet the platform on it."
• You need content negotiation for GraphQL, gRPC, or event schemas — out of scope.

How to Pitch It (Stakeholders)

To executives: We have a recurring, unbudgeted cost every time we change an API: engineers hand-roll version handling and deprecation messaging, inconsistently, and external integrators find out about breaking changes by breaking. This package standardizes that conversation in code — versions are negotiated, deprecations are announced in the response itself, sunset dates become enforceable rather than aspirational. The financial argument is avoided engineering (a credible build-it-yourself cost is weeks of engineering plus indefinite maintenance) and reduced partner-integration support load. The risk argument is honest: it's a small, single-maintainer, pre-1.0 dependency, so we adopt it pinned and treat the option to fork as part of the plan. Recommend a two-week spike against one real endpoint before committing the platform.

To engineering: This is a versioning/negotiation library, not a framework. Expect to write the Laravel service-provider glue, own the middleware ordering, and pin versions — the 0.x line means minor bumps may break us. The payoff is that deprecation and sunset logic stops being bespoke per team and becomes a shared, testable primitive. The latest release (0.1.29) is dependency hygiene only — a signal that upstream is in maintenance mode, not active feature development. Plan accordingly: assume we may own patches, and factor that into the estimate rather than discovering it in month six. Ask: does the versioning convention it imposes match what we'd choose independently? If yes, adopt behind one endpoint and measure; if no, the convention is the valuable part and we can implement it ourselves in a fraction of the integration cost.