Hateoas
A PHP library for adding HATEOAS hypermedia links and embedded resources to REST API representations.
What is Hateoas?
Hateoas is a PHP library that helps developers build HATEOAS-compliant REST APIs by automatically adding hypermedia links and embedded resources to JSON and XML representations. It integrates with JMS Serializer and supports standards like HAL and Atom Links, making APIs more discoverable and self-describing. The library solves the problem of manually managing link generation and resource embedding in API responses.
PHP developers building RESTful web services that need to implement hypermedia controls for API discoverability, especially those using JMS Serializer and frameworks like Symfony or Silex.
Developers choose Hateoas because it provides a standardized, expressive way to add HATEOAS features without reinventing the wheel, with built-in support for pagination, URL generation, and multiple serialization formats. Its tight integration with JMS Serializer and extensible architecture make it a robust choice for hypermedia-driven APIs.
Overview
A PHP library to support implementing representations for HATEOAS REST web services.
Use Cases
Best For
- Adding self-discovery links like 'self', 'next', 'previous' to REST API responses
- Embedding related resources (e.g., user's manager) to reduce client round-trips
- Implementing HAL-compliant JSON or XML outputs for hypermedia APIs
- Handling paginated collections with navigation metadata in APIs
- Generating dynamic URIs using Symfony Expression Language or route generators
- Extending Twig templates with hypermedia link helpers for HTML representations
Not Ideal For
- Projects using serializers other than JMS Serializer (e.g., Symfony Serializer or custom implementations)
- Simple REST APIs that don't require hypermedia controls or discoverable links
- Microservices with minimal dependencies where JMS Serializer and Symfony components add unwanted overhead
- Teams needing highly custom, non-standard hypermedia formats without the resources to implement custom serializers
Pros & Cons
Pros
Seamlessly integrates with JMS Serializer, allowing HATEOAS features to be added directly to serialized objects without extra serialization layers, as shown in the usage examples.
Supports HAL (JSON/XML) and Atom Links (XML) out of the box, making it easy to comply with common hypermedia standards for API responses.
Uses Symfony's Expression Language to generate URIs and conditionally exclude links, enabling flexible, object-driven link creation as demonstrated in the annotations.
Provides representations like PaginatedRepresentation and OffsetRepresentation for handling paginated data with navigation links, reducing boilerplate code for common API patterns.
Cons
Heavily dependent on JMS Serializer; projects using other serialization libraries face significant integration hurdles or cannot use Hateoas without major adjustments.
Requires setup of metadata via annotations, XML, or YAML, along with cache directories and URL generators, which adds initial overhead compared to simpler link-generation approaches.
The README points to separate documentation for versions 1.0, 2.0, and 3.0, indicating potential breaking changes and migration challenges that can confuse users.
Frequently Asked Questions
Related Projects
FusioSelf-Hosted API Management for Builders
NegotiationContent Negotiation tools for PHP.
RestlerZero-boilerplate REST API framework for PHP 8+. Auto-generates routes, docs, validation.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.