Matthias Andreas Benkard | 12a5735 | 2021-12-28 18:02:04 +0100 | [diff] [blame^] | 1 | ``cache`` |
| 2 | ========= |
| 3 | |
| 4 | .. versionadded:: 3.2 |
| 5 | |
| 6 | The ``cache`` tag was added in Twig 3.2. |
| 7 | |
| 8 | The ``cache`` tag tells Twig to cache a template fragment: |
| 9 | |
| 10 | .. code-block:: twig |
| 11 | |
| 12 | {% cache "cache key" %} |
| 13 | Cached forever (depending on the cache implementation) |
| 14 | {% endcache %} |
| 15 | |
| 16 | If you want to expire the cache after a certain amount of time, specify an |
| 17 | expiration in seconds via the ``ttl()`` modifier: |
| 18 | |
| 19 | .. code-block:: twig |
| 20 | |
| 21 | {% cache "cache key" ttl(300) %} |
| 22 | Cached for 300 seconds |
| 23 | {% endcache %} |
| 24 | |
| 25 | The cache key can be any string that does not use the following reserved |
| 26 | characters ``{}()/\@:``; a good practice is to embed some useful information in |
| 27 | the key that allows the cache to automatically expire when it must be |
| 28 | refreshed: |
| 29 | |
| 30 | * Give each cache a unique name and namespace it like your templates; |
| 31 | |
| 32 | * Embed an integer that you increment whenever the template code changes (to |
| 33 | automatically invalidate all current caches); |
| 34 | |
| 35 | * Embed a unique key that is updated whenever the variables used in the |
| 36 | template code changes. |
| 37 | |
| 38 | For instance, I would use ``{% cache "blog_post;v1;" ~ post.id ~ ";" ~ |
| 39 | post.updated_at %}`` to cache a blog content template fragment where |
| 40 | ``blog_post`` describes the template fragment, ``v1`` represents the first |
| 41 | version of the template code, ``post.id`` represent the id of the blog post, |
| 42 | and ``post.updated_at`` returns a timestamp that represents the time where the |
| 43 | blog post was last modified. |
| 44 | |
| 45 | Using such a strategy for naming cache keys allows to avoid using a ``ttl``. |
| 46 | It's like using a "validation" strategy instead of an "expiration" strategy as |
| 47 | we do for HTTP caches. |
| 48 | |
| 49 | If your cache implementation supports tags, you can also tag your cache items: |
| 50 | |
| 51 | .. code-block:: twig |
| 52 | |
| 53 | {% cache "cache key" tags('blog') %} |
| 54 | Some code |
| 55 | {% endcache %} |
| 56 | |
| 57 | {% cache "cache key" tags(['cms', 'blog']) %} |
| 58 | Some code |
| 59 | {% endcache %} |
| 60 | |
| 61 | The ``cache`` tag creates a new "scope" for variables, meaning that the changes |
| 62 | are local to the template fragment: |
| 63 | |
| 64 | .. code-block:: twig |
| 65 | |
| 66 | {% set count = 1 %} |
| 67 | |
| 68 | {% cache "cache key" tags('blog') %} |
| 69 | {# Won't affect the value of count outside of the cache tag #} |
| 70 | {% set count = 2 %} |
| 71 | Some code |
| 72 | {% endcache %} |
| 73 | |
| 74 | {# Displays 1 #} |
| 75 | {{ count }} |
| 76 | |
| 77 | .. note:: |
| 78 | |
| 79 | The ``cache`` tag is part of the ``CacheExtension`` which is not installed |
| 80 | by default. Install it first: |
| 81 | |
| 82 | .. code-block:: bash |
| 83 | |
| 84 | $ composer require twig/cache-extra |
| 85 | |
| 86 | On Symfony projects, you can automatically enable it by installing the |
| 87 | ``twig/extra-bundle``: |
| 88 | |
| 89 | .. code-block:: bash |
| 90 | |
| 91 | $ composer require twig/extra-bundle |
| 92 | |
| 93 | Or add the extension explicitly on the Twig environment:: |
| 94 | |
| 95 | use Twig\Extra\Cache\CacheExtension; |
| 96 | |
| 97 | $twig = new \Twig\Environment(...); |
| 98 | $twig->addExtension(new CacheExtension()); |
| 99 | |
| 100 | If you are not using Symfony, you must also register the extension runtime:: |
| 101 | |
| 102 | use Symfony\Component\Cache\Adapter\FilesystemAdapter; |
| 103 | use Symfony\Component\Cache\Adapter\TagAwareAdapter; |
| 104 | use Twig\Extra\Cache\CacheRuntime; |
| 105 | use Twig\RuntimeLoader\RuntimeLoaderInterface; |
| 106 | |
| 107 | $twig->addRuntimeLoader(new class implements RuntimeLoaderInterface { |
| 108 | public function load($class) { |
| 109 | if (CacheRuntime::class === $class) { |
| 110 | return new CacheRuntime(new TagAwareAdapter(new FilesystemAdapter())); |
| 111 | } |
| 112 | } |
| 113 | }); |