The Expression Language

Hateoas relies on the powerful Symfony ExpressionLanguage component to retrieve values such as links, ids or objects to embed.

Each time you fill in a value (e.g. a Relation href in annotations or YAML), you can either pass a hardcoded value or an expression. To use the Expression Language, use the expr() notation:

/**
 * @Hateoas\Relation("self", href = "expr('/api/users/' ~ object.getId())")
 */

You can learn more about the Expression Syntax in the official documentation.

Context

A special variable named object is available in each expression, and represents the current object:

expr(object.getId())

Adding Your Own Context Variables

Using the HateoasBuilder, you can add your own context variables with the setExpressionContextVariable() method:

use Hateoas\HateoasBuilder;

$hateoas = HateoasBuilder::create()
    ->setExpressionContextVariable('foo', new Foo())
    ->build();

Expression Functions

You can register custom expression functions to extend the expression language. See the Symfony documentation on extending the ExpressionLanguage for more details.

Implement the ExpressionFunctionInterface:

use Hateoas\Expression\ExpressionFunctionInterface;

class MyExpressionFunction implements ExpressionFunctionInterface
{
    public function getName()
    {
        return 'my_func';
    }

    public function getCompiler()
    {
        return function ($arg) {
            // ...
        };
    }

    public function getEvaluator()
    {
        return function ($context, $arg) {
            // ...
        };
    }
}

Then register it with the builder:

$hateoas = HateoasBuilder::create()
    ->registerExpressionFunction(new MyExpressionFunction())
    ->build();

URL Generators

If you use a framework, you might want to generate URLs from route names. This is possible by implementing a custom UrlGenerator. You need to implement the UrlGeneratorInterface:

use Hateoas\UrlGenerator\UrlGeneratorInterface;

class MyUrlGenerator implements UrlGeneratorInterface
{
    public function generate($name, array $parameters, $absolute = false)
    {
        // ...
    }
}

Then register it with the builder. The first argument is the generator name (null for the default generator):

$hateoas = HateoasBuilder::create()
    ->setUrlGenerator(null, new MyUrlGenerator())
    ->build();

Helpers

LinkHelper

The LinkHelper provides a convenient way to retrieve the href value of a link for a given object. You can obtain it from the Hateoas instance:

$linkHelper = $hateoas->getLinkHelper();

$linkHelper->getLinkHref($user, 'self');
// /api/users/42

$linkHelper->getLinkHref($user, 'self', true);
// http://example.com/api/users/42

Twig Extensions

LinkExtension

Hateoas provides Twig extensions. The LinkExtension exposes the getLinkHref() method through the link_href Twig function:

{{ link_href(user, 'self') }}
{# will generate: /users/123 #}

{{ link_href(will, 'self', true) }}
{# will generate: http://example.com/users/123 #}