Caching

There are many different caching features in Revolution. Different aspects of the caching can be extended with user-defined classes, so it is possible to implement different kinds of features in custom component cache mechanisms (i.e. where you cache your own custom data), configure the default cache settings or settings for specific partitions of the core cache, or even extend/override the behavior of all core caching mechanisms by providing your own derivative implementation of [modCacheManager].

How is Caching Done in Revolution?

Revolution isolates different portions of it's core caching into partitions that can be configured and used in isolation. In addition, users can define their own partitions and configure those as needed for custom caching requirements.

First, lets take a look at all of the partitions that are available by default in the core of MODX Revolution.

MODX_CONFIG_KEY If you are using a custom MODX_CONFIG_KEY (i.e. a value other than 'config'), the cache files for that configuration will be in a subdirectory named after the value of MODX_CONFIG_KEY.

System Settings Cache

A collection of the global MODX configuration options, known as System Settings, is the first cache partition loaded by any request to MODX.

2.0.x In MODX 2.0.x releases this is cached to file in the root of the cache directory for the configuration, i.e. core/cache/config.cache.php, by default.

2.1+ In MODX 2.1 and later releases, the config.cache.php file is located in a subdirectory based on the partition name. In this case it would be system_settings which is the default cache_key option defined for this partition.

Context Settings Cache

This partition contains the configuration options for a specific Context, maps of the Resources and URI's that represent those Resources in the Context, along with a Plugin event map for the Context, and the source of the Plugin Elements that are registered in that event map.

2.0.x In MODX 2.0.x, there is a subdirectory of the cache for each Context (i.e. web/ or mgr/) where you will find the context.cache.php file.

2.1+ In MODX 2.1 and later, the files are further isolated into a subdirectory for the partition, named context_settings by default.

Resource (Partial-Page) Cache

The resource cache partition contains the partial-page caching assets for each cacheable Resource. The cache items in this partition contain a cacheable representation of the Resource object as well as representations of any cacheable Element output or other cacheable metadata used by the Resource.

2.0.x In MODX 2.0.x, these cache items are located in the same Context-specific directories as the Context Settings. in a subdirectory called resources/ you will find files named 1.cache.php where the 1 represents the id of the cached Resource.

2.1+ In MODX 2.1 or later, these cache items are organized into Context-specific subdirectories underneath a directory named after the partition, which is resource by default.

Element Cache

Elements that represent PHP scripts (see [modScript] for more information) cache both a representation of the object and an includable copy of the global function which is executed when the script is processed.

2.0.x In MODX 2.0.x, these cache items are stored in an elements subdirectory of the cache, within additional subdirectories for class (i.e. modsnippet or modplugin). Both the object and include file are stored in the same directory as 1.cache.php and 1.include.cache.php where 1 is the id of the Element.

2.1+ In MODX 2.1 and later, this partition is named scripts by default, while the includes are isolated into a separate subdirectory called includes. Both the scripts and includes are then further organized into an elements subdirectory with subdirectories for each class (i.e. modsnippet or modplugin).

Database Cache

If you enable this, MODX can automatically cache database result sets fetched by any xPDOCriteria or xPDOQuery instance. This includes all of the result sets representing xPDOObjects or collections of xPDOObjects returned by methods like getObject and getCollection. This feature can be enabled in environments where database access is more expensive than PHP include time, for instance, when using an external database server, or custom configured for environments with memcached, APC, or other caching systems available. This is again a separate partition from all of the other cache partitions in MODX, most of which are more specific to MODX operations than this one. See xPDO Caching for additional information.

Programmatic Caching

xPDOCacheManager, and the MODX-specific modCacheManager class derived from it, provide some useful features for caching any kind of data to just about any cache system. xPDO includes implementations for file-based, memcached, APC, and WinCache out of the box. There is no tagging feature here as in the programmatic features of the Zend_Cache library, but you can clear specific partitions, or even just parts of a partition in certain implementations.

Clearing by Key Prefix Most cache implementations provide a way to delete specific cache items by regular expressions or key hierarchy, but some, like memcached, do not support this. Providers that do not support this will flush the entire instance (this could include all partitions as well since some providers only allow a single instance) whenever you attempt to delete just specific keys by pattern.

Using modCacheManager

/* write some data to a variable */
$colors = array('red','blue','green');
/* store the variable as a cache item named 'colors' in the default cache provider */
$modx->cacheManager->set('colors',$colors);

/* get that data */
$colors = $modx->cacheManager->get('colors');
foreach ($colors as $color) {
   echo $color.'-';
} /* this echoes 'red-blue-green' */ 
?>

You can optionally set an expiration time on individual cache items:

$str = 'My test cached data.';
$modx->cacheManager->set('testdata',$str,7200);
/* this caches the data for 2 hours. */

Once an item is past it's expiration time, it is not available and next access removes any trace of the cached item.

Refreshing the MODX Cache

Major Change in 2.1 In MODX 2.1 and later, the cache is refreshed instead of cleared and the clearCache() method is deprecated in favor of the new refresh() method. This is an important distinction and one that deserves a better explanation. In particular, the System and Context Settings Cache items are never deleted, only replaced. This transfers the overhead of cache regeneration from the database to the request which is requesting the action, rather than the next request that needs that information. Since this is generally a request in the manager, this greatly improves the apparent performance of the front-end requests since they rarely have to wait for the regeneration activity to complete themselves.

2.0.x MODX 2.0.x users, see the examples under Using modCacheManager::clearCache() at the bottom.

Using modCacheManager::refresh() (for MODX 2.1 and later)

2.1+ This method is only available in MODX 2.1 or later. See Using modCacheManager::clearCache() below for previous releases.

Here are some examples of using modCacheManager->refresh() to refresh various parts of the cache:

/* refresh all the core partitions */
$modx->cacheManager->refresh();

/* refresh the web and web2 context_settings partitions */
$modx->cacheManager->refresh(array(
    'context_settings' => array('contexts' => array('web', 'web2'))
));

/* get all the Contexts */
$contexts = array();
$query = $this->xpdo->newQuery('modContext');
$query->select($this->xpdo->escape('key'));
if ($query->prepare() && $query->stmt->execute()) {
    $contexts = $query->stmt->fetchAll(PDO::FETCH_COLUMN);
}
/* refresh the default partitions in the default order, excluding the mgr Context */
$results = array();
$modx->cacheManager->refresh(array(
    'auto_publish' => array('contexts' => array_diff($contexts, array('mgr'))),
    'system_settings' => array(),
    'context_settings' => array('contexts' => $contexts),
    'db' => array(),
    'scripts' => array(),
    'default' => array(),
    'resource' => array('contexts' => array_diff($contexts, array('mgr'))),
    'menu' => array(),
    'action_map' => array(),
    'lexicon_topics' => array()
), $results);
/* var_dump the results collected from the refresh operation on each partition */
var_dump($results);

Using modCacheManager::clearCache() (for MODX 2.0.x only)

Deprecated in 2.1 This method is deprecated in MODX 2.1 and will not be available starting in version 2.2.

Here are some examples of using modCacheManager->clearCache():

// clear all the usual stuff by default (all files with the extension .cache.php
// in the cachePath + all object caches)
$modx->cacheManager->clearCache();

// clear only cache files with extension .php or .log in the web/ custom/
// or logs/ paths; no objects are cleared
$paths = array('web/', 'custom/', 'logs/');
$options = array('objects' => null, 'extensions' => array('.php', '.log'));
$modx->cacheManager->clearCache($paths, $options);

// clear all cache files with extension .php in the cachePath
// + all objects + execute the timed publishing checks
$paths = array('');
$options = array('objects' => '*', 'publishing' => true, 'extensions' => array('.php'));
$modx->cacheManager->clearCache($paths, $options);

See Also

• Caching in xPDO
• xPDOCacheManager

Namespaces

Advanced Development

Custom Manager Pages