Skip to content

Cache System

The Cache System is being used for caching generated data between requests to reduce I/O and Database load by reusing already calculated content. It implements a basic key/value interface and uses various configurable caching backends. A working cache system is essential for a good performance.

Cache Handler

APCU (Default)

APCU is the default caching backend if no configuration is made. It provides an easy and fast caching system as it runs directly as module in PHP. It is recommended for small to medium XELOS installations on a single server setup. In case of large installations or cluster setups you need to switch to REDIS or MEMCACHE as APCU doesn't support a distributed cache storage. If the PHP library IGBINARY is installed it will automatically be used for serialization of cache data resulting in faster and smaller cache usage.

Configuration

// FILE: config.custom.php

define('XF_CACHE_TYPE', 'apcu');

REDIS

REDIS is the preferred caching backend for medium to large installations and can be used for SESSION storage as well in this case (see Session). If the PHP library IGBINARY is installed it will automatically be used for serialization of cache data resulting in faster and smaller cache usage.

Configuration

// FILE: config.custom.php

// Required
define('XF_CACHE_TYPE', 'redis');
define('XF_CACHE_SERVER', '[redis_host_or_ip]');

// Optional
define('XF_CACHE_AUTH', '[redis_authentication]');
define('XF_CACHE_DATABASE', '[redis_database_id, default: 0]');

Memcache

MEMCACHE is another distributed cache backend which is supported for legacy issues. In terms of speed, features and future proof we recommend using REDIS for new installations.

Configuration

// FILE: config.custom.php

define('XF_CACHE_TYPE', 'memcache');
define('XF_CACHE_SERVER', '[memcached_host_or_ip]');

Using the Cache

Setting and Getting Values

Using the set() and get() functions to set and get data from the configured cache is quite simple:

$XF = xf::instance();
$XF->lib->cache->set('myVariable', 'ValueToStore');
// New Request
$XF->lib->cache->get('myVariable');

Warning

Make sure the sepcified variable is unique as it is being used across the whole system. Best practice is to preprend a unique namespace for module or the instance as cache group: e.g. XM_MY_MODULE/VARIABLE

Cache Groups

Cache Groups allow to combine multiple keys into one group to facilitate invalidation of caches by group. E.g. if you are caching multiple different values which are user dependent it would make sense to include the current user id in the cache group to allow clearing all user specific caches at once. The cache group is "hierarchical", so you can have nested groups. e.g. XM_MY_MODULE/POLICY/USER_1/VARIABLE - that way you can clear all caches of your module, all policy caches or all caches of a specific user.

There are also a few predefined system wide cache groups which should be used if want to take advantage of centralized cache invalidation on predetermined events (e.g. user logs in):

Cache Group Description Invalidation
TEMPLATE Template Caching --
SESSION Session Caching --
SYSTEM System Caching --
DB Database Query Caching --

Cache Status

To see current statistics as cache usage and hit ratios visit the /system_admin/cache/ page on your system. It gives detailed information depending on your configured cache backend:

Cache Dashboard

Manual Cache Clearing

You can manually clear the cache by using the CACHE Control on the upper right in your Admin Bar. Or by using the command line tool:

> php xf cache clear