Understanding Http Caching, ESI and Fragments¶

One of the best features of Symfony is its use of Edge Side Includes or ESI. This is where different parts of your page are rendered as small esi tags. Before your user sees these, a middle layer parses them out, makes another request back to your app for just that fragment, and then combines it all together.

This is the “fragments” framework at work: the page is broken down into small pieces and each has a special URL to render it all by itself. This lets you cache the different fragments of your page independently. Since the middle cache layer puts all the fragments together, your user has no idea you’re doing all this voodoo behind the scenes.

{# This is the 2.1 syntax for fragments (or sub-requests) %}
{% render 'EventBundle:NewFeatures:inner' with {
    'color': 'lightblue'
}, {
    'standalone': true
} %}

Welcome fragments and ProxyListener, goodbye internal.xml¶

Before Symfony 2.2, this special URL came from importing the internal.xml routing file, which exposed a regular Symfony route that was capable of rendering any controller.

# app/config/routing.yml
_internal:
    resource: "@FrameworkBundle/Resources/config/routing/internal.xml"
    prefix:   /_internal

If you used this route, you were supposed to somehow make sure that the URL was protected so that only your caching layer could use it. If a normal user had access to this, they could render any controller with any arguments in your system, which would be a bummer...

In Symfony 2.2, the internal.xml routing file is gone. Let’s remove it and replace it with a fragments key in config.yml. Instead of a route, this activates a listener that watches for any requests that start with /_proxy, which is the URL that the ESI tags now render as. This alone doesn’t help security, except that the listener uses a few tricks internally, which we’ll talk more about in a moment.

# app/config/config.yml
framework:
    esi:             ~
    fragments:       { path: /_proxy }
    # ...

The new Twig render Syntax¶

For now, let’s get our application working! Aside from this configuration change, the render tag now looks different. First, it isn’t a tag at all anymore, it’s now a function that’s rendered using the double-curly brace syntax:

Second, when you reference the controller, you must wrap it in a call to a new Twig controller function. For now, I’ll remove the standalone key that activated ESI:

{{ render(controller('EventBundle:NewFeatures:inner', {
    'color': 'lightblue'
})) }}

When we refresh the page, things finally work! Looking at the timeline, we see information about the main request and the inner fragment. This is how things look when we’re not using ESI - the full page and the inner fragment render all at once. This is called the default rendering strategy and it’s pretty straightforward.

Activating ESI¶

Since that’s boring, let’s activate ESI! To do this, just change the function to render_esi:

{{ render_esi(controller('EventBundle:NewFeatures:inner', {
    'color': 'lightblue'
})) }}

Refresh again! It renders exactly the same, how exciting! But actually, a lot just changed behind the scenes. The main page now renders everything except the inner area. Instead, it prints out an ESI tag. Our caching layer parses it, makes another request into Symfony for that piece and then combines it all together. This is called the ESI rendering strategy, because the first main request returns an ESI tag in place of the inner area.

{{ render_hinclude(controller('EventBundle:NewFeatures:inner', {
    'color': 'lightblue'
})) }}

Fragment URL Security¶

Let’s look a little bit more at the URL in the HInclude tag. If we open this URL directly we can see the content that will be rendered. In fact, regardless of whether you use the ESI or HInclude strategy, this URL is used to allow an outside layer to request the individual fragments. This was activated by adding the fragments key to config.yml.

So what prevents an evil user from exploiting this URL to render any controller in our system with any parameters? Nothing! Just kidding, there are two built in protections: trusted proxies and signed URLs.

framework
    trusted_proxies:
        - 192.168.12.0