Hateoas Bundle Laravel Package

Product Decisions This Supports

• API contract strategy: hypermedia vs. static schemas. This bundle lets you ship responses where each resource carries its own _links/relations, so the decision "do we expose HATEOAS affordances to clients?" becomes a cheap experiment instead of a multi-sprint architecture project. You can pilot on one resource and measure client impact.
• Build vs. buy for link/relation plumbing. Every API team eventually writes the same code: turn a route + entity + relation into a URL, resolve rel names, embed sub-resources, keep it consistent across endpoints. This package replaces that with annotation/config-driven declaration. The "buy" side is genuinely cheaper here — the build cost is low but the drift cost (inconsistent rel naming across teams) is what actually hurts.
• Versioning roadmap. Hypermedia is primarily a decoupling tool: clients follow links rather than hardcoded paths, so adding or moving endpoints doesn't force a client release. That directly informs whether you commit to a v1 → v2 migration or can evolve in place. This is the strongest strategic argument for the package and the one worth putting on a roadmap slide.
• Client portfolio decisions. If you have multiple heterogeneous consumers (mobile app on a slow release train, partner integrations, a JS SPA), the value scales with client count and release-cadence mismatch. With one first-party client, the benefit largely evaporates.
• Partner/developer enablement. Self-describing responses reduce integration support load and make API docs derivable from the relation graph rather than hand-maintained. This is a support-cost line item, not just a technical one.
• Sequencing decision: adoption vs. spike. Given the weak adoption signal, the near-term decision is really "fund a timeboxed spike" (~1–2 weeks, one mid-complexity resource) rather than "adopt org-wide." That decision belongs in a quarterly planning conversation, not an architecture review board.

When to Consider This Package

Adopt (or spike) when:

• You are on Symfony, not Laravel. This is a Symfony bundle wired through the DI container, annotations, and — critically — JMS Serializer. It is not portable to Laravel without a rewrite. Treat any "PHP package" framing as a red flag in your own evaluation.
• You already use FOSRestBundle + JMS Serializer; the bundle composes with that stack rather than replacing it. If you're on API Platform or plain symfony/serializer, the integration savings shrink substantially.
• You have three or more client types with mismatched release cadences, or external partners you cannot force to upgrade on your schedule.
• You want to standardize rel naming across teams that currently invent it ad hoc — the annotation model gives you a reviewable, greppable contract.
• You are comfortable owning the code. With ~94 stars and zero dependents in the dependency graph, plan for a vendored fork with a named internal owner. Budget a modest annual maintenance allowance (PHP/Symfony version bumps, serializer compatibility).

Look elsewhere when:

• You're on Laravel — evaluate API Platform (Symfony) or spatie/laravel-fractal-style transformers for the same problem; this bundle is the wrong tool.
• You have a single first-party client — the discoverability payoff doesn't cover the annotation overhead and the fork liability.
• Your clients are machine-to-machine with generated stubs, or you're on gRPC/GraphQL — the problem this solves isn't your problem, and GraphQL solves discoverability natively.
• You need a maintainer SLA, security advisories, or a commercial support path. There is no evidence of that here, and the dependency signal suggests limited production hardening.
• Your team lacks Symfony serializer internals expertise — debugging annotation-driven response shaping without that skill is a hidden cost.
• The API surface is small and stable (a handful of CRUD endpoints). You can hand-roll links in a base controller in a day.

How to Pitch It (Stakeholders)

To executives: This is a low-cost way to make our API self-describing, which means clients adjust to changes by following links instead of us coordinating releases with every consumer. That buys us fewer breaking-change migrations and lower partner-integration support cost. The package itself is small and unmaintained-by-community, so the honest framing is: we're buying a proven head start and taking ownership of the code — a one-time engineering investment plus a small ongoing maintenance line, not a vendor dependency. Recommendation is a two-week spike on a single endpoint before any broader commitment.

To engineering: Annotation-driven, Symfony-native, composes with JMS Serializer and FOSRestBundle; removes per-controller link boilerplate and puts rel naming under code review. Caveats to state plainly: it is not actively maintained at scale, it is Symfony-only, and we should fork it, pin it, and assign an owner. The spike deliverable is a single resource with links + one embedded relation, plus a written assessment of what a fork would cost us per Symfony major. If the spike shows more yak-shaving than boilerplate savings, we stop — the exit cost is near zero at that scope.