ezurl() links in eZ Publish 5

In eZ Publish 4 / legacy, formatting link URLs is handled by the well-known ezurl() template operator. This is especially useful when you have multiple siteaccesses and you use URL-based matching. In eZ Publish 5, there is no single ezurl() equivalent; instead, there are several options depending on the type of link you want to display.

In eZ Publish legacy, you can pass any string to ezurl() and it will handle leading slashes and prepend the siteaccess name if necessary.  You could pass a URL alias or any custom path:

{$node.url_alias|ezurl()}
{'my_module/my_view/(param1)/value1'|ezurl()}
{$search_result.url_alias|ezurl()}
{$external_path|ezurl()}

eZ Publish 5 is more strict, as it tries to validate the type of link you want to create.  It uses the path Twig function but its usage depends on the type of destination link.

To link to a location/node object, you use the object directly:

{{ path( location_object ) }}

If you have a location/node ID only, you must pass in "ez_urlalias" as the first argument and then supply the location ID:

{{ path( 'ez_urlalias', {'locationId': content.contentInfo.mainLocationId} ) }}

If you are linking to a legacy module view, you must pass in "ez_legacy" as the first argument and then supply the module path:

{{ path( 'ez_legacy', { 'module_uri': 'my_module/my_view/(param1)/value1' } ) }}

If you are linking to a Symfony route, you must pass in the route identifier (not the route path) and then any required or desired parameters:

{{ path( 'job_application', { 'jobID': 55 } ) }}

Since an arbitrary path string is not supported, there are at least a couple of non-covered edge cases:

• If you're linking to a page outside of the content management system but you still need to preserve the siteaccess name in the URL
• If you have a search result path (not a Location object)

One way to solve this is to create your own Twig function. See the Twig documentation on the steps to set up custom functions. Here is an example of the important functionality for an ezurl()-like Twig function in eZ Publish 5. Note that it is only intended to cover the case where you are using URL-based matching.

public function ezurlFunctions($url)
{
    $currentSiteaccess = $this->globalHelper->getSiteaccess();
    $siteAccessName = $currentSiteaccess->name;

    // Inject the siteaccess name if we are using URI matching and if we are not in the default siteaccess
    // ezpublish.siteaccess.default maps to the actual setting ezpublish.siteaccess.default_siteaccess
    if( $siteAccessName != $this->container->getParameter( 'ezpublish.siteaccess.default' ) )
    {
        $matcherName = $currentSiteaccess->matcher->getName();
        if( $matcherName == 'uri:map' )
        {
            $url = $currentSiteaccess->matcher->analyseLink( $url );
        }
    }
    return $url;
}

You can then use that Twig function similarly to how you would use the legacy ezurl() template operator:

{{ '/path/to/page'|ezurl }}