The HateoasBuilder

The HateoasBuilder provides numerous methods to configure and customize the Hateoas serializer. It follows the builder pattern, allowing you to chain method calls and finalize the configuration by calling build().

XML Serializer

You can set a custom XML serializer using the following method:

• setXmlSerializer(XmlSerializerInterface $xmlSerializer): sets the XML serializer used to serialize links and embedded resources in XML format.

JSON Serializer

Similarly, you can set a custom JSON serializer:

• setJsonSerializer(JsonSerializerInterface $jsonSerializer): sets the JSON serializer used to serialize links and embedded resources in JSON format.

URL Generator

URL generators are responsible for generating URLs from route definitions. You can register named URL generators to support different routing strategies:

• setUrlGenerator($name, UrlGeneratorInterface $urlGenerator): adds a new named URL generator. The name is used to reference the generator in your route annotations.

Expression Evaluator/Expression Language

The expression language allows you to use dynamic values in your annotations. The following methods let you configure the expression evaluator:

• setExpressionContextVariable($name, $value): adds a new expression context variable, making it available within expression strings.
• setExpressionLanguage(ExpressionLanguage $expressionLanguage): replaces the default expression language instance with a custom one.
• registerExpressionFunction(ExpressionFunctionInterface $expressionFunction): adds a new expression function that can be used within expression strings.

Relation Provider

Relation providers allow you to programmatically define relations for your resources. You can register additional resolvers for custom relation providers:

• addRelationProviderResolver(RelationProviderResolverInterface $resolver): adds a new relation provider resolver to the chain of resolvers.

(JMS) Serializer Specific

These methods are specific to the JMS Serializer integration and allow you to configure how serialization metadata is discovered and loaded:

• includeInterfaceMetadata($include): whether to include the metadata from interfaces when serializing objects.
• setMetadataDirs(array $namespacePrefixToDirMap): sets a map of namespace prefixes to directories. This overrides any previously defined directories.
• addMetadataDir($dir, $namespacePrefix = ''): adds a directory in which the serializer will look for class metadata.
• addMetadataDirs(array $namespacePrefixToDirMap): adds a map of namespace prefixes to directories for metadata lookup.
• replaceMetadataDir($dir, $namespacePrefix = ''): similar to addMetadataDir(), but overrides an existing entry if one already exists for the given namespace prefix.

For more information, refer to the official Serializer documentation.

Others

Additional configuration methods:

• setDebug($debug): enables or disables debug mode. When enabled, the cache will be flushed automatically on changes.
• setCacheDir($dir): sets the cache directory where compiled metadata will be stored.

Configuring a Cache Directory

Hateoas collects metadata about your objects from various sources such as YML, XML, or annotation definitions. In order to avoid parsing this information on every request, you should configure a cache directory where the library can store the processed metadata:

$builder = \Hateoas\HateoasBuilder::create();

$hateoas = $builder
    ->setCacheDir($someWritableDir)
    ->build();

Configuring Metadata Locations

By default, the library uses Doctrine annotations to read metadata from your classes. However, you can also define metadata in XML or YAML files. Use the addMetadataDir() method to register directories where these files are located:

$hateoas = \Hateoas\HateoasBuilder::create()
    ->addMetadataDir($someDir)
    ->build();

Metadata files should be named after the fully qualified class name where backslashes are replaced with dots. For example, the metadata file for the class Acme\Demo\Representation\User would be named Acme.Demo.Representation.User.yml (or .xml).

Extending The Library

Hateoas has been designed with extensibility in mind. The library can be extended in several ways to accommodate your specific needs:

• Adding custom serializers — implement XmlSerializerInterface or JsonSerializerInterface to control how links and embedded resources are rendered in the output format of your choice.
• Implementing custom URL generators — create your own UrlGeneratorInterface implementation to integrate with any routing system or framework.
• Adding expression functions — register custom expression functions to extend the expression language with domain-specific logic.
• Creating relation providers — build custom relation provider resolvers to define relations programmatically based on your application's requirements.