170 lines
5.8 KiB
PHP
170 lines
5.8 KiB
PHP
<?php
|
|
|
|
/**
|
|
* @file
|
|
*
|
|
* Plugins to handle cache-indirection.
|
|
*
|
|
* Simple plugin management to allow clients to more tightly control where
|
|
* object caches are stored.
|
|
*
|
|
* CTools provides an object cache mechanism, and it also provides a number
|
|
* of subsystems that are designed to plug into larger systems. When doing
|
|
* caching on multi-step forms (in particular during AJAX operations) these
|
|
* subsystems often need to operate their own cache. In reality, its best
|
|
* for everyone if they are able to piggyback off of the larger cache.
|
|
*
|
|
* This system allows this by registering plugins to control where caches
|
|
* are actually stored. For the most part, the subsystems could care less
|
|
* where the data is fetched from and stored to. All it needs to know is
|
|
* that it can 'get', 'set' and 'clear' caches. Additionally, some caches
|
|
* might need extra operations such as 'lock' and 'finalize', and other
|
|
* operations may be needed based upon the specific uses for the cache
|
|
* plugins.
|
|
*
|
|
* To utilize cache plugins, there are two pieces of data. First, there is
|
|
* the mechanism, which is simply the name of the plugin to use. CTools
|
|
* provides a 'simple' mechanism which goes straight through to the object
|
|
* cache. The second piece of data is the 'key' which is a unique identifier
|
|
* that can be used to find the data needed. Keys can be generated any number
|
|
* of ways, and the plugin must be agnostic about the key itself.
|
|
*
|
|
* That said, the 'mechanism' can be specified as pluginame::data and that
|
|
* data can be used to derive additional data. For example, it is often
|
|
* desirable to NOT store any cached data until original data (i.e, user
|
|
* input) has been received. The data can be used to derive this original
|
|
* data so that when a 'get' is called, if the cache is missed it can create
|
|
* the data needed. This can help prevent unwanted cache entries from
|
|
* building up just by visiting edit UIs without actually modifying anything.
|
|
*
|
|
* Modules wishing to implement cache indirection mechanisms need to implement
|
|
* a plugin of type 'cache' for the module 'ctools' and provide the .inc file.
|
|
* It should provide callbacks for 'cache set', 'cache get', and 'cache clear'.
|
|
* It can provide callbacks for 'break' and 'finalize' if these are relevant
|
|
* to the caching mechanism (i.e, for use with locking caches such as the page
|
|
* manager cache). Other operations may be utilized but at this time are not part
|
|
* of CTools.
|
|
*/
|
|
|
|
/**
|
|
* Fetch data from an indirect cache.
|
|
*
|
|
* @param string $mechanism
|
|
* A string containing the plugin name, and an optional data element to
|
|
* send to the plugin separated by two colons.
|
|
*
|
|
* @param string $key
|
|
* The key used to identify the cache.
|
|
*
|
|
* @return mixed
|
|
* The cached data. This can be any format as the plugin does not necessarily
|
|
* have knowledge of what is being cached.
|
|
*/
|
|
function ctools_cache_get($mechanism, $key) {
|
|
return ctools_cache_operation($mechanism, $key, 'get');
|
|
}
|
|
|
|
/**
|
|
* Store data in an indirect cache.
|
|
*
|
|
* @param string $mechanism
|
|
* A string containing the plugin name, and an optional data element to
|
|
* send to the plugin separated by two colons.
|
|
*
|
|
* @param string $key
|
|
* The key used to identify the cache.
|
|
*
|
|
* @param mixed $object
|
|
* The data to cache. This can be any format as the plugin does not
|
|
* necessarily have knowledge of what is being cached.
|
|
*/
|
|
function ctools_cache_set($mechanism, $key, $object) {
|
|
return ctools_cache_operation($mechanism, $key, 'set', $object);
|
|
}
|
|
|
|
/**
|
|
* Clear data from an indirect cache.
|
|
*
|
|
* @param string $mechanism
|
|
* A string containing the plugin name, and an optional data element to
|
|
* send to the plugin separated by two colons.
|
|
*
|
|
* @param string $key
|
|
* The key used to identify the cache.
|
|
*/
|
|
function ctools_cache_clear($mechanism, $key) {
|
|
return ctools_cache_operation($mechanism, $key, 'clear');
|
|
|
|
}
|
|
|
|
/**
|
|
* Perform a secondary operation on an indirect cache.
|
|
*
|
|
* Additional operations, beyond get, set and clear may be items
|
|
* such as 'break' and 'finalize', which are needed to support cache
|
|
* locking. Other operations may be added by users of the indirect
|
|
* caching functions as needed.
|
|
*
|
|
* @param string $mechanism
|
|
* A string containing the plugin name, and an optional data element to
|
|
* send to the plugin separated by two colons.
|
|
*
|
|
* @param string $key
|
|
* The key used to identify the cache.
|
|
*
|
|
* @param string $op
|
|
* The operation to call, such as 'break' or 'finalize'.
|
|
*
|
|
* @param mixed $object
|
|
* The cache data being operated on, in case it is necessary. This is
|
|
* optional so no references should be used.
|
|
*
|
|
* @return mixed
|
|
* The operation may or may not return a value.
|
|
*/
|
|
function ctools_cache_operation($mechanism, $key, $op, $object = NULL) {
|
|
list($plugin, $data) = ctools_cache_find_plugin($mechanism);
|
|
if (empty($plugin)) {
|
|
return;
|
|
}
|
|
|
|
$function = ctools_plugin_get_function($plugin, "cache $op");
|
|
if (empty($function)) {
|
|
return;
|
|
}
|
|
|
|
return $function($data, $key, $object, $op);
|
|
}
|
|
|
|
/**
|
|
* Take a mechanism and return a plugin and data.
|
|
*
|
|
* @param string $mechanism
|
|
* A string containing the plugin name, and an optional data element to
|
|
* send to the plugin separated by two colons.
|
|
*
|
|
* @return array
|
|
* An array, the first element will be the plugin and the second element
|
|
* will be the data. If the plugin could not be found, the $plugin will
|
|
* be NULL.
|
|
*/
|
|
function ctools_cache_find_plugin($mechanism) {
|
|
if (strpos($mechanism, '::') !== FALSE) {
|
|
// use explode(2) to ensure that the data can contain double
|
|
// colons, just in case.
|
|
list($name, $data) = explode('::', $mechanism, 2);
|
|
}
|
|
else {
|
|
$name = $mechanism;
|
|
$data = '';
|
|
}
|
|
|
|
if (empty($name)) {
|
|
return array(NULL, $data);
|
|
}
|
|
|
|
ctools_include('plugins');
|
|
$plugin = ctools_get_plugins('ctools', 'cache', $name);
|
|
return array($plugin, $data);
|
|
}
|