How does template caching work? 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 &amp; where to use caching.

I know the answer is probably complex, but I'd still love to know... How does caching work?
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.