Twig

The flexible, fast, and secure
template engine for PHP

a Symfony Product
Docs Tags cache
You are reading the documentation for Twig 3.x. Switch to the documentation for Twig 1.x. 2.x.

Questions & Feedback

License

Twig documentation is licensed under the new BSD license.

cache

New in version 3.2

The cache tag was added in Twig 3.2.

The cache tag tells Twig to cache a template fragment:

1
2
3
{% cache "cache key" %}
    Cached forever (depending on the cache implementation)
{% endcache %}

If you want to expire the cache after a certain amount of time, specify an expiration in seconds via the ttl() modifier:

1
2
3
{% cache "cache key" ttl(300) %}
    Cached for 300 seconds
{% endcache %}

The cache key can be any string that does not use the following reserved characters {}()/\@:; a good practice is to embed some useful information in the key that allows the cache to automatically expire when it must be refreshed:

  • Give each cache a unique name and namespace it like your templates;
  • Embed an integer that you increment whenever the template code changes (to automatically invalidate all current caches);
  • Embed a unique key that is updated whenever the variables used in the template code changes.

For instance, I would use {% cache "blog_post;v1;" ~ post.id ~ ";" ~ post.updated_at %} to cache a blog content template fragment where blog_post describes the template fragment, v1 represents the first version of the template code, post.id represent the id of the blog post, and post.updated_at returns a timestamp that represents the time where the blog post was last modified.

Using such a strategy for naming cache keys allows to avoid using a ttl. It's like using a "validation" strategy instead of an "expiration" strategy as we do for HTTP caches.

If your cache implementation supports tags, you can also tag your cache items:

1
2
3
4
5
6
7
{% cache "cache key" tags('blog') %}
    Some code
{% endcache %}

{% cache "cache key" tags(['cms', 'blog']) %}
    Some code
{% endcache %}

The cache tag creates a new "scope" for variables, meaning that the changes are local to the template fragment:

1
2
3
4
5
6
7
8
9
10
{% set count = 1 %}

{% cache "cache key" tags('blog') %}
    {# Won't affect the value of count outside of the cache tag #}
    {% set count = 2 %}
    Some code
{% endcache %}

{# Displays 1 #}
{{ count }}

Note

The cache tag is part of the CacheExtension which is not installed by default. Install it first:

1
$ composer require twig/cache-extra

On Symfony projects, you can automatically enable it by installing the twig/extra-bundle:

1
$ composer require twig/extra-bundle

Or add the extension explicitly on the Twig environment:

1
2
3
4
use Twig\Extra\Cache\CacheExtension;

$twig = new \Twig\Environment(...);
$twig->addExtension(new CacheExtension());

If you are not using Symfony, you must also register the extension runtime:

1
2
3
4
5
6
7
8
9
10
11
12
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Adapter\TagAwareAdapter;
use Twig\Extra\Cache\CacheRuntime;
use Twig\RuntimeLoader\RuntimeLoaderInterface;

$twig->addRuntimeLoader(new class implements RuntimeLoaderInterface {
    public function load($class) {
        if (CacheRuntime::class === $class) {
            return new CacheRuntime(new TagAwareAdapter(new FilesystemAdapter()));
        }
    }
});
Website powered by Symfony and Twig, deployed on
The Twig logo is © 2010-2021 Symfony