Version 3 end of life
This version of Silverstripe CMS will not recieve any additional bug fixes or documentation updates. Go to documentation for the most recent stable version.

Caching

Built-In Caches

The framework uses caches to store infrequently changing values. By default, the storage mechanism is simply the filesystem, although other cache backends can be configured. All caches use the SS_Cache API.

The most common caches are manifests of various resources:

Flushing the various manifests is performed through a GET parameter (flush=1). Since this action requires more server resources than normal requests, executing the action is limited to the following cases when performed via a web request:

  • The environment is in "dev mode"
  • A user is logged in with ADMIN permissions
  • An error occurs during startup

The Cache API

The SS_Cache class provides a bunch of static functions wrapping the Zend_Cache system in something a little more easy to use with the SilverStripe config system.

A Zend_Cache has both a frontend (determines how to get the value to cache, and how to serialize it for storage) and a backend (handles the actual storage).

Rather than require library code to specify the backend directly, cache consumers provide a name for the cache backend they want. The end developer can then specify which backend to use for each name in their project's configuration. They can also use 'all' to provide a backend for all named caches.

End developers provide a set of named backends, then pick the specific backend for each named cache. There is a default File cache set up as the 'default' named backend, which is assigned to 'all' named caches.

Using Caches

Caches can be created and retrieved through the SS_Cache::factory() method. The returned object is of type Zend_Cache.

	// foo is any name (try to be specific), and is used to get configuration 
	// & storage info
	$cache = SS_Cache::factory('foo'); 
	if (!($result = $cache->load($cachekey))) {
		$result = caluate some how;
		$cache->save($result, $cachekey);
	}
	return $result;

backends clear out entries based on age and maximum allocated storage. If you include the version of the object in the cache key, even object changes don't need any invalidation. You can force disable the cache though, e.g. in development mode.

	// Disables all caches
	SS_Cache::set_cache_lifetime('any', -1, 100);

Keep in mind that Zend_Cache::CLEANING_MODE_ALL deletes all cache entries across all caches, not just for the 'foo' cache in the example below.

	$cache = SS_Cache::factory('foo'); 
	$cache->clean(Zend_Cache::CLEANING_MODE_ALL);
	$cache = SS_Cache::factory('foo');  
	$cache->remove($cachekey);

it often pays to increase the lifetime of caches ("TTL"). It defaults to 10 minutes (600s) in SilverStripe, which can be quite short depending on how often your data changes. Keep in mind that data expiry should primarily be handled by your cache key, e.g. by including the LastEdited value when caching DataObject results.

	// set all caches to 3 hours
	SS_Cache::set_cache_lifetime('any', 60*60*3);

SS_Cache segments caches based on the versioned reading mode. This prevents developers from caching draft data and then accidentally exposing it on the live stage without potentially required authorisation checks. This segmentation is automatic for all caches generated using SS_Cache::factory method.

Data that is not content sensitive can be cached across stages by simply opting out of the segmented cache with the disable-segmentation argument.

## Alternative Cache Backends

By default, SilverStripe uses a file-based caching backend.
Together with a file stat cache like [APC](http://us2.php.net/manual/en/book.apc.php) 
this is reasonably quick, but still requires access to slow disk I/O.
The `Zend_Cache` API supports various caching backends ([list](http://framework.zend.com/manual/1.12/en/zend.cache.backends.html))
which can provide better performance, including APC, Xcache, ZendServer, Memcached and SQLite.

## Cleaning caches on flush=1 requests

If `?flush=1` is requested in the URL, e.g. http://mysite.com?flush=1, this will trigger a call to `flush()` on
any classes that implement the `Flushable` interface. Using this, you can trigger your caches to clean.

See [reference documentation on Flushable](/developer_guides/execution_pipeline/flushable/) for implementation details.

### Memcached

This backends stores cache records into a [memcached](http://www.danga.com/memcached/) 
server. memcached is a high-performance, distributed memory object caching system. 
To use this backend, you need a memcached daemon and the memcache PECL extension.

 	:::php
// _config.php 
SS_Cache::add_backend(
	'primary_memcached',
	'Memcached',
	array(
		'servers' => array(
			'host' => 'localhost', 
			'port' => 11211, 
			'persistent' => true, 
			'weight' => 1, 
			'timeout' => 5,
			'retry_interval' => 15, 
			'status' => true, 
			'failure_callback' => null
		)
	)
);
SS_Cache::pick_backend('primary_memcached', 'any', 10);
If your Memcached instance is using a local Unix socket instead of a network port:

 	:::php
// _config.php 
SS_Cache::add_backend(
	'primary_memcached',
	'Memcached',
	array(
	  	'servers' => array(
			'host' => 'unix:///path/to/memcached.socket',
			'port' => 0,
			'persistent' => true,
			'weight' => 1,
			'timeout' => 5,
			'retry_interval' => 15,
			'status' => true,
			'failure_callback' => null
		)
	)
);
SS_Cache::pick_backend('primary_memcached', 'any', 10);
This backends stores cache records in shared memory through the [APC](http://pecl.php.net/package/APC)
 (Alternative PHP Cache) extension (which is of course need for using this backend).

```php
	SS_Cache::add_backend('primary_apc', 'APC');
	SS_Cache::pick_backend('primary_apc', 'any', 10);

This backend is an hybrid one. It stores cache records in two other backends: a fast one (but limited) like Apc, Memcache... and a "slow" one like File or Sqlite.

Edit on Github