IronCache

IronCache is an extension for ExpressionEngine 2 that implements whole-page caching using memcached, an extremely fast memory caching daemon.  It was originally pontificated upon elsewhere, was inspired by the BatCache plugin for WordPress and has been in use at Grist for about 18 months now.  It is designed to massively reduce the stress on high-traffic sites running EE, and decrease page load times.  We wrote IronCache because it was useful to us — we hope the same for you.

Update:  IronCache is now MSM compatible.  Thanks to Lee Hilton for his testing on this.

How does IronCache work?
Features of IronCache
What do I need in order to use IronCache?
Warnings
Who supports IronCache?
Downloading and installing IronCache
Configuring your cache
Shout Outs

How does IronCache work?

IronCache works by providing a shortcut to EE.  Under conditions that you specify, EE will save a complete copy of its output to memcached using a URI-unique key.  Then, early in each front-end page request , IronCache causes EE to quickly check the cache for that particular page’s key.  If found, it outputs the HTML for the page and exits, rather than going through the rest of its rather long and expensive song and dance.  This saves a great deal of PHP work and reduces the number of database queries required to load a page to a bare minimum.

Features of IronCache

- It is highly configurable. Caching hit/miss is by URI pattern (regex).  The extension will cache only those URIs of your site that you want it to, and will cache each part with the sensitivity and duration that you specify.  For example, you could set a 5 minute cache on your homepage with very high sensitivity, while caching your internal pages for 10 minutes at a relatively low sensitivity.

- It is login aware.  For logged-in sessions, it’s as if IronCache did not even exist — EE  does everything normally.

- It provides a header hint.  Want to know if your page came from IronCache, or if IronCache is working?  Check the headers!

What do I need in order to use IronCache?

- You will need to know how to write simple regular expressions.  Part of configuring Ironcache involves telling it what URLs to cache, and you will use regex to do that.  Mistakes here can lead to rather large problems with your cache.

- You will need a running memcached daemon,  You should also know how to support and interact with memcached.

- You will need to be running ExpressionEngine 2.2, since this is the only environment we’ve tested IronCache on.  It may work on earlier versions of EE2, but we’re not sure.  There’s no public EE 1.x version.

- More generally:  please only use this extension if you know what you are doing — misconfiguration could bring down your site.

Warnings

- IronCache fails gracefully if your memcached instance suddenly goes away, but it should not be run in the absence of a working, configured memcached server because it can make your site marginally slower.

- Part of the magic of IronCache is that it extends EE’s native Output class.  If you are running other add-ons that also do this (run the command `grep -rl ‘extends EE_Output’` on your extensions and/or thrid_party folders to tell for sure) IronCache and/or the other extension may not work, though there are sometimes work-arounds for this.

Who supports IronCache?

Glad you asked because this is important.  NO ONE!  We’re releasing this software into the wild because it’s been useful for us, but we can’t guarantee that it will work in any particular situation.  We’ve cleaned it up and standardized it as best we can, and will respond to questions and bug reports as we are able, but please know that you’re using this software at your own risk.  Have an improvement? Write it up and let us know on github and we’ll fold it in.

Downloading and installing IronCache

(we strongly suggest doing this in a test environment, rather than a live site.)

1. Download the extension.
2.  Unpack the folder as required and move the folder called ironcache into the third_party directory of your EE2 instance.  (make sure the permissions on everything in the folder are correct and that it is executable by the user running apache etc.)
3.  From EE control panel, install the extension, which should now be on the extension list.
4. Open the settings screen for IronCache, and configure your cache (see below.)
5. That’s it you’re done!

Configuring your cache

enabled:  turns the cache on and off

memcached host:  the host for your memcached instance

memcached port:  the port for memcached (default: 11211)

prefix:  a string that will append to all of your keys.  This allows EE to share the same cache with various other applications or environments

caching configuration:  a strictly formatted string that controls how IronCache works.  Each line of the configuration looks like this:

pattern||cache_time||counter_reset||threshold

pattern:  a regular expression that will match against your URIs.  Leave this empty to write a rule caching the homepage.
cache_time:  once cached, pages of this type will stay in cache for this long, in seconds
counter_reset:  the sensitivity counter will reset in this many seconds
threshold:  if the page is viewed this many times in counter_reset seconds, it gets cached

This can be summarized in the following sentence:  if a page with URI matching pattern is generated threshold times in counter_reset seconds, it is placed in the cache for cache_time seconds.

Examples:

^article||300||10||2

A rule that will cache any page whose URL begins with the string “article” for five minutes if it is viewed twice in ten seconds.

^cars|^trucks|^motorbikes||600||1||1

A rule that will cache any page whose URL begins with any of the strings “cars” “trucks” or “motorbikes” for ten minutes if it is viewed even once.

||1200||10||3

A rule that will cache the homepage for twenty minutes if it is viewed three times in ten seconds.

Shout-Outs

IronCache was made by Darcy Christ (@1000camels), Nathan Letsinger (@natebot) and Matt Perry (@mattoperry) at Grist.

This software was inspired by BatCache for WordPress, and was written in the day or so following a conversation with Matt Mullenweg.

Special thanks to Brian Litzinger for his early and very helpful comment.