The {% cache %} tag is quite powerful, and can be used to greatly increase the performance of templates.

But ultimately the whole thing is still pretty mysterious. I can see three tables in the database which seem to relate to caching:

  • craft_templatecachecriteria
  • craft_templatecacheelements
  • craft_templatecaches

I'm still trying to grasp how it all ties together... If I can get a better understanding of how it all works in the "big picture", it will help me to make better decisions as to when & where to use caching.

I know the answer is probably complex, but I'd still love to know... How does caching work?

1 Answer 1


Cache Creation

The primary files to look at are Cache_Node.php in app/etc/templating/twigextensions and TemplateCacheService.php in app/services.

The Cache Node does some basic checking before deciding what content to output, and what to do with that content. It builds a cache key (either automatically, or uses the one defined), and then looks for an existing cached template. If a cache is found for that key, it is outputted and the template process moves on. If no cache is found for that key, the caching process begins.

If the cache node is not in a situation where caching is being ignored (either Live Preview or a config setting), then it starts caching with the Template Cache Service. That service has a method called startTemplateCache. This method creates an array of element queries and element IDs that are stored under the cache key.

The template within the cache node is then compiled with Twig's subcompile method. While this is happening, the element queries and resulting element IDs are stored in the previously created arrays. The compiled result is then placed in a variable and then given (along with the other cache parameters) to the endTemplateCache method.

The endTemplateCache method stores the cache in the templatecaches table. It also loops over the element criteria and element id arrays to tag the caches using the templatecachecriteria and templatecacheelements respectively.

Finally, the cache tag outputs the body (cached or otherwise).

Cache Clearing

When you make changes to elements in the control panel, the Template Cache Service does one or two things to clear caches:

  • If the element was modified or deleted, it will check the templatecacheelements table to immediately clear any caches that it knows the element was involved in.

  • If the element was added or modified, it queues up a new “Delete Stale Template Caches” task, which cycles through the templatecachecriteria table to see if there are any cached element queries which (if not cached) would have started showing the just-saved element. If the query returns the element, its corresponding cache will be deleted.

  • Thanks Bryan. I still dream of a Template Cache Service that does not only clear the caches but also updates them. :)
    – carlcs
    Jan 20, 2015 at 23:33
  • That would just be a matter of building a plugin that extends the Template Cache Service to include such a feature, and then building a new Twig extension to call that instead of the default. Personally that seems a tad resource intensive. Jan 20, 2015 at 23:41
  • Excellent, thanks Bryan for the detailed answer! And thanks Brandon for the additional notes on cache clearing!
    – Lindsey D
    Jan 25, 2015 at 5:00
  • @BryanRedeagle re: to your comment about extending TemplateCacheService - I don't think that would work, because the BaseTemplate (which populates the Element IDs when the template is compiled) will call the load the default "templateCache" component, instead of a custom one (or is there a way to overwrite configuration so that your custom templateCache service in Craft is loaded instead of the default one?). Jul 20, 2015 at 15:33
  • Really, both would end up being loaded. That's why you need to build a new Twig tag. The Twig tag is what's calling the Template Cache Service. You would also need to make sure you had the same hooks set up to clear your cache when changes are made. Jul 20, 2015 at 15:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.