Hateoas

Hateoas helps PHP applications implement the HATEOAS (Hypermedia As The Engine Of Application State) constraint for REST APIs by attaching links, embedded resources, and relations to your existing model objects via PHP attributes, annotations, XML, or YAML configuration — without changing the models themselves. It builds on top of JMS Serializer, adding relation metadata and a expression-language-driven link generator so hypermedia controls are computed from your object graph at serialization time.

Out of the box it ships serializers for plain JSON, HAL+JSON, and XML/XML-HAL, plus helpers and Twig extensions for rendering links outside of serialized payloads, and a PagerfantaFactory for exposing paginated collections with first/last/next/previous relations.

What You Get

• HateoasBuilder fluent API for configuring serializers, URL generators, and metadata drivers
• #[Relation]/#[Embedded]/#[Exclusion] attributes (plus annotation/XML/YAML equivalents) for declaring hypermedia links without touching model classes
• Built-in JSON, HAL+JSON, XML, and XML-HAL serializers, extensible with custom formats
• Symfony ExpressionLanguage-driven link conditions, a LinkHelper/Twig LinkExtension for non-serialized rendering, and PagerfantaFactory for paginated collection relations

Common Use Cases

• PHP/Symfony REST APIs that need discoverable, self-describing hypermedia links (self, next, edit, delete) on resource responses
• APIs adopting the HAL or JSON:API-adjacent conventions for embedding related resources inline with relation metadata
• Paginated API endpoints exposing first/last/next/previous navigation links via PagerfantaFactory

Under The Hood

Architecture — At serialize time, AddRelationsListener hooks into JMS Serializer’s event system to inspect each object’s Hateoas metadata (loaded through the configured MetadataFactory/driver chain), resolve its LinkFactory-built links and EmbeddedsFactory-built embedded resources (evaluating any Relation conditions via Symfony’s ExpressionLanguage), and inject the result into the serialized output through format-specific serializers (JsonHalSerializer, XmlSerializer, etc.) implementing a shared SerializerInterface.

Tech Stack — PHP 8.1+, PSR-4 autoloaded under Hateoas\. Built directly on jms/serializer and jms/metadata for object graph traversal and metadata caching, and symfony/expression-language for relation-condition evaluation. Optional integrations include doctrine/annotations (legacy annotation config), symfony/routing (SymfonyRouteFactory for URL generation), symfony/yaml, and twig/twig for the Twig link extension.

Code Quality — Backed by a tests/ suite using PHPUnit and Prophecy for mocking, covering builders, factories, serializers, and URL generators. The project follows Doctrine Coding Standard (doctrine/coding-standard) and ships GitHub Actions CI plus a separate coding-standards workflow, though recent commit activity is low, consistent with a mature, largely feature-complete library.

API Design — Configuration is declarative and colocated with models via attributes/annotations rather than requiring separate DTOs or wrapper classes, so existing domain objects gain hypermedia behavior by adding metadata, not by inheriting from a base class or reshaping the object graph — a design that keeps the library from leaking into core business logic.