Twig

The flexible, fast, and secure
template engine for PHP

a Symfony Product
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" tag('blog') %}
    Some code
{% endcache %}

{% cache "cache key" tag(['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" tag('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:

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:

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