Symfony Route Deprecation Bundle Laravel Package

Product Decisions This Supports

• API lifecycle policy as a shipped product surface. This bundle lets you attach Deprecation (and, by convention, Sunset) headers to specific routes, turning "we're retiring v1" from a changelog paragraph or email blast into a machine-readable contract that client SDKs, API gateways, and customer tooling can act on automatically. That is a product decision about how you communicate breaking changes, not just an engineering detail.
• Roadmap sequencing for versioning work. If your roadmap includes v2 of a public API, the deprecation-signaling layer is a prerequisite, not a follow-up. Adopting a signaling mechanism early lets you run the overlap window (v1 deprecated → v2 default → v1 sunset) with observable dates rather than a big-bang cutover.
• Support-cost reduction / breaking-change budget. Deprecation headers reduce the long tail of "why did my integration stop working" tickets by giving integrators advance, parseable warning. This is a defensible input to a decision like "can we afford to retire v1 this half?"
• Build vs. buy skews strongly to "build small." The functional surface is thin — a response listener that injects a header with a timestamp and optional link. That means the PM decision is really "do we adopt a dependency or vendor ~50 lines of listener code?" For a 9-star, zero-dependent package, the honest default is to vendor the behavior and keep the header contract as our spec, not a third party's.
• Enterprise/B2B contract compliance. If customers negotiate API stability terms, having a documented, standards-aligned deprecation mechanism is a procurement and security-review talking point. The IETF framing is useful in those conversations even if you implement it in-house.
• Ecosystem-fit caveat that changes the decision: this is a Symfony bundle, not a Laravel package. In a Laravel codebase the adoption cost is a re-implementation (middleware or a response macro), not a composer require. The PM decision for a Laravel shop is therefore "adopt the pattern," not "adopt the package."

When to Consider This Package

Adopt (or, more likely, borrow the pattern) when all of these hold:

• The service is Symfony-based and routes are the unit of deprecation.
• You have external or cross-team consumers whose clients can read response headers — i.e. the signal has somewhere to land.
• You have an actual deprecation policy with dates, or are about to write one. A header with no sunset date and no owner is worse than silence.
• You want a low-ceremony, standards-aligned implementation and are comfortable pinning/vendoring it.

Look elsewhere — or write it yourself — when:

• You're on Laravel. Use a middleware or a Route::macro; ~30–60 lines. Adding a Symfony bundle here is a category error.
• You need RFC-level rigor. The package targets the IETF draft; the Deprecation header was standardized as RFC 9745 (with Sunset in RFC 8594). Verify the package's format matches the final spec before you expose it to customers, or you'll ship a contract you have to break.
• Maturity matters. 9 stars, 0 dependents, single-maintainer risk, and a low composite score mean no support path, no security-response process, and no guarantee of a Symfony major-version bump. Do not put this on a critical path without a fork plan.
• You need more than headers. If the real requirement is deprecation analytics (who's still calling v1?), an API portal, per-consumer notification, or contract testing, headers are one input and you need a gateway/observability solution, not a bundle.
• Routes aren't the right granularity — e.g. you're deprecating fields, event schemas, or SDK methods rather than endpoints.

How to Pitch It (Stakeholders)

One-liner for executives: A small, low-risk mechanism for telling API consumers in the response itself that an endpoint is going away and when — so version retirements happen on schedule instead of stalling on support escalations.

The ask: Not budget. Approval to standardize a deprecation signaling convention (headers per RFC 9745 / RFC 8594) across our API surface, plus a decision on whether we take the open-source package as a dependency or implement the listener in-house.

Why now: Every planned breaking change is gated on our ability to communicate it credibly. Shipping the signal is cheap; retrofitting it after consumers are surprised is expensive in trust and support load.

Why low risk: The scope is a response header. It is additive, backward-compatible, and reversible. The package itself is MIT and tiny — but because it is a Symfony bundle with minimal adoption and follows a draft spec, engineering should treat the header contract as ours and the library as an implementation detail we can replace or vendor without customer impact.

What engineering should confirm before we commit: (1) final-RFC header format and date encoding, (2) how route-level metadata is declared and kept in sync with our sunset calendar, (3) whether we vendor or depend given maintenance risk, (4) how we'll measure the effect — e.g. share of v1 traffic from consumers that have received the header.