cache
Cache arbitrary chunks of your templates and layouts
The {{ cache }}
tag (added in v1.10) is an easy yet powerful way to speed up page load times by caching any rendered chunk of your template that you wish. To cache a part of any template, simply wrap it in {{ cache }} {{ /cache }}
tags. Assuming this feature is enabled, the default settings should be good enough for people that just want a little more speed without a ton of work.
However, if you want to get the most out of caching, there are a number of great features that come included.
Turning It On
To enable the cache tags, set the enable
setting to true
in the settings file, then add the tags to your templates wherever you’d like. Simple as that.
Configuring
This tag comes with three optional parameters:
for
— the length of time that this tag’s cache is valid for, the default value is12 hours
(this default value can be set in cache’s configuration file)key
— one or more keys (pipe-delimited) to associate with this tag, this/these key(s) will be useful later if you choose to use the automated cache invalidation features (more on those in a bit)scope
— eithersite
orpage
; setting this topage
will force the cacher to treat the cache tags on this page uniquely to those found on other pages,site
by default
Scopes
There are two scopes that can be used for caching: site
and page
.
When a tag uses the site
scope (which is the default value, as set in cache’s settings file), similar cache tags across your entire site will share cache files if possible. This serves two purposes: fewer files being stored in the cache, and less full rendering that needs doing. This is recommended for most scenarios.
When the scope is set to page
, that cache tag is considered specific to the page that it was viewed on. The only time that the page
scope is useful is when the current URL affects the output of the template chunk being cached.
As an example, see the default site that comes with Statamic. In the right side-bar, there is a mini-calendar of the next two upcoming events. This is the same on every page, and the URL doesn’t change the results, so keeping the scope at site
makes sense.
However, if you want to cache the entire layout of every page (which, yes, that’s possible), the URL will determine what gets filled in for the {{ layout_content }}
tag, so the scope for this tag will need to be set to page
.
It’s highly recommended that you keep the default_scope
set to site
, and overriding per tag where needed by setting the scope
parameter to page
.
How It Works
The content between the {{ cache }}
and {{ /cache }}
tags is hashed to create a unique key for that tag. The cacher then checks to see if a cache for that unique key already exists. If it does, it displays that information. Otherwise, it renders out the content, stores that rendered HTML for use later, and then displays that information.
If cached HTML does already exist but its older than either the for
length if it’s set, or otherwise the default_cache_length
in the settings, it will be erased and the content will be re-rendered and re-cached.
Keys & Automated Cache Invalidation
If you’ve ever used classes on HTML elements as an easy way to quick grab a bunch of elements with JavaScript, then you’re already familiar with how keys work. Setting a key
on a tag makes a note internally that that key is linked to that cache tag. You can set multiple keys per tag, just separate them with a pipe (|
).
There are a couple of built in hooks that will automatically invalidate the caches of keys that you’ve chosen based on events that happen throughout the system. These can be set in the settings:
publish_invalidation
— whenever content is published in the control panel, this list is checked for matching folder(s) and when matches are found, the associated key(s)’ caches are deleted; both folders and keys here can be pipe-delimited lists, and the folder list can use wildcardsnew_day_invalidation
— every day, the first visit to your site will invalidate all of the keys in this list; this is helpful if you have content that could change daily, but not more often than that; a calendar, for example
For example, let’s say each {{ entries:listing }}
tag on your site is wrapped in a cache tag with the key blog-listing
. Every time someone publishes something to the blog
folder, you want to delete the caches for all caches with the blog-listing
key. In cache’s settings, you’ll use the publish_invalidation
setting like so:
publish_invalidation:
-
folder: blog
key: blog-listing
Whenever content is published and its folder matches blog
, all caches with the key blog-listing
are deleted immediately.
Clean Up
There’s one last setting in the settings file: garbage_threshold
. The cacher will attempt to keep itself clean so that you don’t have a bunch of useless cache files hanging around your system. Each week, the cacher will automatically run garbage collection. When it does this, it will compare all of its cached HTML chunks’ timestamps against the value set for garbage_threshold
. If the cache is older, it will be deleted.
Further, all key references internally will also get cleaned up — old cache hashes removed, and key references completely deleted in the cases where no relevant hashes remain.
You don’t need to fully understand how this clean up part works, but hopefully it’s helpful to know that we’re doing our best to clean up after ourselves.