Learn

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 is 12 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 — either site or page; setting this to page 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 wildcards
  • new_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.

This article was last updated on September 13th, 2016. Find an error? Please let us know!