``cache``
=========

.. versionadded:: 3.2

    The ``cache`` tag was added in Twig 3.2.

The ``cache`` tag tells Twig to cache a template fragment:

.. code-block:: twig

    {% 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:

.. code-block:: twig

    {% 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:

.. code-block:: twig

    {% 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:

.. code-block:: twig

    {% 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:

    .. code-block:: bash

        $ composer require twig/cache-extra

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

    .. code-block:: bash

        $ 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()));
                }
            }
        });