BazingaHateoasBundle

BazingaHateoasBundle integrates the Hateoas library into Symfony applications, letting REST APIs express HATEOAS-style hypermedia links, embedded resources, and relations directly through JMS Serializer annotations or PHP attributes. It removes the boilerplate of manually assembling _links and _embedded blocks, so controllers can return plain domain objects while the bundle handles link generation, relation resolution, and pagination metadata at serialization time.

The bundle has shipped since 2013 and remains the de-facto way to add hypermedia affordances to Symfony REST APIs that already rely on JMSSerializerBundle, with a stable API surface and continued compatibility updates through Symfony 7/8 and PHP 8.1+.

What You Get

• Symfony service wiring for Hateoas’s link and relation providers, auto-registered via the bundle’s DependencyInjection extension
• Support for both Doctrine annotations and native PHP 8.1+ attributes to declare @Relation links on entities
• An Expression Language function integration for conditional link generation based on request or object state
• Transparent hooking into JMS Serializer so _links/_embedded output appears without custom normalizers
• Configuration options for exclusion strategies, relation providers, and URL generation exposed through Symfony’s config tree

Common Use Cases

• Adding HAL-style _links and _embedded sections to JSON responses from a Symfony REST API
• Building hypermedia-driven APIs where clients navigate via server-provided relation links rather than hardcoded routes
• Attaching pagination metadata (next/prev/self links) to collection endpoints
• Exposing conditional links (e.g. an edit relation only when the current user has permission) via Expression Language rules

Under The Hood

Architecture - The bundle is a thin Symfony DependencyInjection layer: BazingaHateoasExtension registers the underlying Hateoas library’s serialization subscriber, link/relation providers, and URL generator as Symfony services, wiring them into the already-configured jms_serializer service via compiler passes in DependencyInjection/Compiler. Application code never calls the bundle directly; it declares @Relation/#[Relation] metadata on entities and the subscriber intercepts JMS Serializer’s normalization pass to inject _links/_embedded output.

Tech Stack - Pure PHP 8.1+ targeting Symfony 5.4 through 8.0 and JMSSerializerBundle 3-5, with Symfony’s ExpressionLanguage component used for conditional link rules and Doctrine annotations supported alongside native attributes for backward compatibility.

Code Quality - The repository ships a small, focused test suite (7 files) under Tests/DependencyInjection covering the extension and compiler passes, plus PHPUnit and PHP_CodeSniffer configuration enforced in CI; core Hateoas link-resolution logic itself lives in the separate willdurand/hateoas library and is tested there rather than in this bundle’s repo.

API Design - The public surface is entirely declarative (attributes/annotations plus YAML/XML bundle configuration), so consuming code requires no direct API calls beyond enabling the bundle and configuring jms_serializer; this keeps integration low-boilerplate but means understanding the API means reading the separate Hateoas library’s annotation reference.