Using ESI in Symfony

First, to use ESI, be sure to enable it in your application configuration:

1
2
3
4

# config/packages/framework.yaml
framework:
    # ...
    esi: true

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <!-- ... -->
        <framework:esi enabled="true"/>
    </framework:config>
</container>

1
2
3
4
5
6
7
8

// config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    $framework->esi()
        ->enabled(true)
    ;
};

Now, suppose you have a page that is relatively static, except for a news ticker at the bottom of the content. With ESI, you can cache the news ticker independently of the rest of the page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// src/Controller/DefaultController.php
namespace App\Controller;

// ...
class DefaultController extends AbstractController
{
    public function about(): Response
    {
        $response = $this->render('static/about.html.twig');
        $response->setPublic();
        $response->setMaxAge(600);

        return $response;
    }
}

In this example, the response is marked as public to make the full page cacheable for all requests with a lifetime of ten minutes. Next, include the news ticker in the template by embedding an action. This is done via the render() helper (for more details, see how to embed controllers in templates).

As the embedded content comes from another page (or controller for that matter), Symfony uses the standard render helper to configure ESI tags:

1
2
3
4
5
6
7

{# templates/static/about.html.twig #}

{# you can use a controller reference #}
{{ render_esi(controller('App\\Controller\\NewsController::latest', { 'maxPerPage': 5 })) }}

{# ... or a URL #}
{{ render_esi(url('latest_news', { 'maxPerPage': 5 })) }}

By using the esi renderer (via the render_esi() Twig function), you tell Symfony that the action should be rendered as an ESI tag. You might be wondering why you would want to use a helper instead of just writing the ESI tag yourself. That's because using a helper makes your application work even if there is no gateway cache installed.

When using the default render() function (or setting the renderer to inline), Symfony merges the included page content into the main one before sending the response to the client. But if you use the esi renderer (i.e. call render_esi()) and if Symfony detects that it's talking to a gateway cache that supports ESI, it generates an ESI include tag. But if there is no gateway cache or if it does not support ESI, Symfony will just merge the included page content within the main one as it would have done if you had used render().

The embedded action can now specify its own caching rules entirely independently of the main page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// src/Controller/NewsController.php
namespace App\Controller;

// ...
class NewsController extends AbstractController
{
    public function latest(int $maxPerPage): Response
    {
        // sets to public and adds some expiration
        $response->setSharedMaxAge(60);

        return $response;
    }
}

In this example, the embedded action is cached publicly too because the contents are the same for all requests. However, in other cases you may need to make this response non-public and even non-cacheable, depending on your needs.

Putting all the above code together, with ESI the full page cache will be valid for 600 seconds, but the news component cache will only last for 60 seconds.

When using a controller reference, the ESI tag should reference the embedded action as an accessible URL so the gateway cache can fetch it independently of the rest of the page. Symfony takes care of generating a unique URL for any controller reference and it is able to route them properly thanks to the FragmentListener that must be enabled in your configuration:

1
2
3
4

# config/packages/framework.yaml
framework:
    # ...
    fragments: { path: /_fragment }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <!-- ... -->
    <framework:config>
        <framework:fragment path="/_fragment"/>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9

// config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework) {
    // ...
    $framework->fragments()
        ->path('/_fragment')
    ;
};

One great advantage of the ESI renderer is that you can make your application as dynamic as needed and at the same time, hit the application as little as possible.

The render_esi helper supports two other useful options:

alt

Used as the alt attribute on the ESI tag, which allows you to specify an alternative URL to be used if the src cannot be found.

ignore_errors

If set to true, an onerror attribute will be added to the ESI with a value of continue indicating that, in the event of a failure, the gateway cache will remove the ESI tag silently.