Content Caching

Speed up your site.

Most Statamic sites won’t amass a ton of pages over their lifetime. Even ambitious bloggers may only create one- or two-hundred pages over the course of a couple of years. However, there are a handful of folks that create much larger sites.

In earlier versions of Statamic, large sites — that is, sites with hundreds of pages — started to see slow-downs when trying to render pages. Our testing found that at that scale, even a simple entry-listing was taking over a second to put together. For computers, that’s a long time. We had to do something about this.

As of v1.5, Statamic comes with content caching built in.

How It Works

The very first time your site loads in a browser, Statamic reads all of your content files’ front-matter and stores that information into a couple of well-organized lists within one cache file. When it comes time to find your content, rather than needing to dig through hundreds of files — opening the file, checking to see if it’s what we need, closing the file, repeat — Statamic only needs to open one file and get what it needs from that.

On each subsequent visit to your site, Statamic examines all your content files to see if anything has changed. If something is different — whether that’s something new, updated, or gone — Statamic updates your cache file with just those changes. If you have hundreds of content files, you may see a small delay during your first visit, but each visit after that will be lightning quick. (Assuming you’re not changing hundreds of files before each page load, and even if for some reason you are, things are still much faster than without caching.)

Why It Works

Opening, reading, and closing a file from the filesystem isn’t a terribly time-consuming process by itself, but when you do it hundreds (or even thousands) of times for one page load, those little bits really start to stack up. By not needing to open up tons of files to build a page, rendering speeds increase dramatically, cutting page-load time by over two-thirds in some scenarios.

This means that whether your site has tens or hundreds of files, every page load is quick while still being assembled dynamically.

What Gets Cached

Only your content’s front-matter gets stored into the content cache. We do this for average-use-case reasons. Our testing found that on average, front-matter was generally pretty small, while content-areas were generally pretty big. Storing everything into your cache made the cache file huge on big sites, to the point that opening that one large file and working with it was becoming just as slow as opening hundreds of files.

Keeping your content out of the cache allows the cache file to stay a more manageable size for both working with and storing. Virtually all filtering and sorting happens with front-matter variables anyway; Statamic first finds the files needed to build the page being viewed and then only works with those files.

Furthermore, Statamic’s content-display tags (like {{ entries:listing }} et al.) have been upgraded to only open content files when its absolutely necessary. If your listing tag never displays {{ content }}, Statamic doesn’t need to open the content file — everything can come straight from the cache. This makes things even faster.

Sounds Great, How Do I Enable Caching?

You don’t have to do anything, caching is on by default for every Statamic site running v1.5 or later.

We originally made it an option to turn caching on (or to turn it off if we had defaulted it to being on), but we quickly realized that this would mean needing to account for two scenarios for every content-retrieval action. That makes maintaining Statamic twice as hard for us, and when you’re getting the same end-result, we couldn’t see why anyone would want to choose to make things slower. So there’s nothing you need to do, caching is on.

Your Cache Files

Your cache file is stored here:

/_cache/_app/content/

You will see two files in here:

• content.php contains your content cache
• last.php contains a UNIX timestamp of the last time the cache was updated, this is used to determine what’s changed and what needs updating within the cache

Gotchas

The caching system works quite well, but there may be times when you’ll need to clear your cache. Examples of when this might be needed:

• you move your site — _cache folder and all — to a new server
• you change site settings that change URL- or file-paths
• you were manually editing the cache file for some reason — you shouldn’t be in there anyway

note If your site isn’t rendering quite as you’d expect, your first step should be to clear out the cache.

How to Clear the Cache

Perform the following steps:

• Delete the _cache/_app/content folder
• Visit your site in browser

Statamic will see that you don’t have a content cache (or even the folder to hold the cache) and will completely rebuild it for you.