HTTP Cache

Caching on the Shoulders of Giants

With HTTP Caching, you cache the full output of a page (i.e. the response) and bypass your application entirely on subsequent requests. Caching entire responses isn't always possible for highly dynamic sites, or is it? With Edge Side Includes (ESI), you can use the power of HTTP caching on only fragments of your site.

The Symfony cache system is different because it relies on the simplicity and power of the HTTP cache as defined in RFC 7234 - Caching. Instead of reinventing a caching methodology, Symfony embraces the standard that defines basic communication on the Web. Once you understand the fundamental HTTP validation and expiration caching models, you'll be ready to master the Symfony cache system.

Since caching with HTTP isn't unique to Symfony, many articles already exist on the topic. If you're new to HTTP caching, Ryan Tomayko's article Things Caches Do is highly recommended. Another in-depth resource is Mark Nottingham's Cache Tutorial.

Caching with a Gateway Cache

When caching with HTTP, the cache is separated from your application entirely and sits between your application and the client making the request.

The job of the cache is to accept requests from the client and pass them back to your application. The cache will also receive responses back from your application and forward them on to the client. The cache is the "middle-man" of the request-response communication between the client and your application.

Along the way, the cache will store each response that is deemed "cacheable" (See HTTP Cache). If the same resource is requested again, the cache sends the cached response to the client, ignoring your application entirely.

This type of cache is known as an HTTP gateway cache and many exist such as Varnish, Squid in reverse proxy mode, and the Symfony reverse proxy.

1
2
3
4

# config/packages/framework.yaml
when@prod:
    framework:
        http_cache: true

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

<!-- 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">

    <when env="prod">
      <framework:config>
          <!-- ... -->
          <framework:http-cache enabled="true"/>
      </framework:config>
    </when>
</container>

1
2
3
4
5
6
7
8

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

return static function (FrameworkConfig $framework, string $env): void {
    if ('prod' === $env) {
        $framework->httpCache()->enabled(true);
    }
};

Making your Responses HTTP Cacheable

Once you've added a reverse proxy cache (e.g. like the Symfony reverse proxy or Varnish), you're ready to cache your responses. To do that, you need to communicate to your cache which responses are cacheable and for how long. This is done by setting HTTP cache headers on the response.

HTTP specifies four response cache headers that you can set to enable caching:

• Cache-Control
• Expires
• ETag
• Last-Modified

These four headers are used to help cache your responses via two different models:

1. Expiration Caching Used to cache your entire response for a specific amount of time (e.g. 24 hours). Simple, but cache invalidation is more difficult.
2. Validation Caching More complex: used to cache your response, but allows you to dynamically invalidate it as soon as your content changes.

1
2
3
4
5
6
7
8
9

// src/Controller/BlogController.php
use Symfony\Component\HttpKernel\Attribute\Cache;
// ...

#[Cache(public: true, maxage: 3600, mustRevalidate: true)]
public function index(): Response
{
    return $this->render('blog/index.html.twig', []);
}

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

// src/Controller/BlogController.php
use Symfony\Component\HttpFoundation\Response;

public function index(): Response
{
    // somehow create a Response object, like by rendering a template
    $response = $this->render('blog/index.html.twig', []);

    // cache publicly for 3600 seconds
    $response->setPublic();
    $response->setMaxAge(3600);

    // (optional) set a custom Cache-Control directive
    $response->headers->addCacheControlDirective('must-revalidate', true);

    return $response;
}

1

Cache-Control: public, maxage=3600, must-revalidate

1
2
3
4
5

// marks the Response stale
$response->expire();

// forces the response to return a proper 304 response with no content
$response->setNotModified();

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

// use this method to set several cache settings in one call
// (this example lists all the available cache settings)
$response->setCache([
    'must_revalidate'  => false,
    'no_cache'         => false,
    'no_store'         => false,
    'no_transform'     => false,
    'public'           => true,
    'private'          => false,
    'proxy_revalidate' => false,
    'max_age'          => 600,
    's_maxage'         => 600,
    'immutable'        => true,
    'last_modified'    => new \DateTime(),
    'etag'             => 'abcdef'
]);

Cache Invalidation

Cache invalidation is not part of the HTTP specification. Still, it can be really useful to delete various HTTP cache entries as soon as some content on your site is updated.

For details, see Cache Invalidation.

Using Edge Side Includes

When pages contain dynamic parts, you may not be able to cache entire pages, but only parts of it. Read Working with Edge Side Includes to find out how to configure different cache strategies for specific parts of your page.

HTTP Caching and User Sessions

Whenever the session is started during a request, Symfony turns the response into a private non-cacheable response. This is the best default behavior to not cache private user information (e.g. a shopping cart, a user profile details, etc.) and expose it to other visitors.

However, even requests making use of the session can be cached under some circumstances. For example, information related to some user group could be cached for all the users belonging to that group. Handling these advanced caching scenarios is out of the scope of Symfony, but they can be solved with the FOSHttpCacheBundle.

In order to disable the default Symfony behavior that makes requests using the session uncacheable, add the following internal header to your response and Symfony won't modify it:

1
2
3

use Symfony\Component\HttpKernel\EventListener\AbstractSessionListener;

$response->headers->set(AbstractSessionListener::NO_AUTO_CACHE_CONTROL_HEADER, 'true');

Summary

Symfony was designed to follow the proven rules of the road: HTTP. Caching is no exception. Mastering the Symfony cache system means becoming familiar with the HTTP cache models and using them effectively. This means that, instead of relying only on Symfony documentation and code examples, you have access to a world of knowledge related to HTTP caching and gateway caches such as Varnish.

Learn more