.. index::
single: Cache; ESI
single: ESI
.. _edge-side-includes:
Working with Edge Side Includes
===============================
Gateway caches are a great way to make your website perform better. But they
have one limitation: they can only cache whole pages. If your pages contain
dynamic sections, such as the user name or a shopping cart, you are out of
luck. Fortunately, Symfony provides a solution for these cases, based on a
technology called `ESI`_, or Edge Side Includes. Akamai wrote this specification
in 2001 and it allows specific parts of a page to have a different
caching strategy than the main page.
The ESI specification describes tags you can embed in your pages to communicate
with the gateway cache. Only one tag is implemented in Symfony, ``include``,
as this is the only useful one outside of Akamai context:
.. code-block:: html
.. note::
Notice from the example that each ESI tag requires a fully-qualified URL.
An ESI tag represents a page fragment that can be fetched via the given
URL.
When a request is handled, the gateway cache fetches the entire page from
its cache or requests it from the backend application. If the response contains
one or more ESI tags, these are processed in the same way. In other words,
the gateway cache either retrieves the included page fragment from its cache
or requests the page fragment from the backend application again. When all
the ESI tags have been resolved, the gateway cache merges each into the main
page and sends the final content to the client.
All of this happens transparently at the gateway cache level (i.e. outside
of your application). As you'll see, if you choose to take advantage of ESI
tags, Symfony makes the process of including them almost effortless.
.. _using-esi-in-symfony2:
Using ESI in Symfony
~~~~~~~~~~~~~~~~~~~~
First, to use ESI, be sure to enable it in your application configuration:
.. configuration-block::
.. code-block:: yaml
# config/packages/framework.yaml
framework:
# ...
esi: { enabled: true }
.. code-block:: xml
.. code-block:: php
// config/packages/framework.php
$container->loadFromExtension('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::
// src/Controller/DefaultController.php
// ...
class DefaultController extends AbstractController
{
public function about()
{
$response = $this->render('static/about.html.twig');
// sets the shared max age - which also marks the response as public
$response->setSharedMaxAge(600);
return $response;
}
}
In this example, the full-page cache has 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
:ref:`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:
.. code-block:: twig
{# 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.
.. tip::
As you'll see below, the ``maxPerPage`` variable you pass is available
as an argument to your controller (i.e. ``$maxPerPage``). The variables
passed through ``render_esi`` also become part of the cache key so that
you have unique caches for each combination of variables and values.
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()``.
.. note::
Symfony detects if a gateway cache supports ESI via another Akamai
specification that is supported out of the box by the Symfony reverse
proxy.
The embedded action can now specify its own caching rules entirely independently
of the master page::
// src/Controller/NewsController.php
namespace App\Controller;
// ...
class NewsController extends AbstractController
{
public function latest($maxPerPage)
{
// ...
$response->setSharedMaxAge(60);
return $response;
}
}
With ESI, the full page cache will be valid for 600 seconds, but the news
component cache will only last for 60 seconds.
.. _http_cache-fragments:
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
:class:`Symfony\\Component\\HttpKernel\\EventListener\\FragmentListener`
that must be enabled in your configuration:
.. configuration-block::
.. code-block:: yaml
# config/packages/framework.yaml
framework:
# ...
fragments: { path: /_fragment }
.. code-block:: xml
.. code-block:: php
// config/packages/framework.php
$container->loadFromExtension('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.
.. caution::
The fragment listener only responds to signed requests. Requests are only
signed when using the fragment renderer and the ``render_esi`` Twig
function.
.. note::
Once you start using ESI, remember to always use the ``s-maxage``
directive instead of ``max-age``. As the browser only ever receives the
aggregated resource, it is not aware of the sub-components, and so it will
obey the ``max-age`` directive and cache the entire page. And you don't
want that.
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.
.. _`ESI`: http://www.w3.org/TR/esi-lang