Docs For Class Cache

Description

Cache_Store provides the public interface for working with the cache system. Internally it uses one or more engines to service requests.

It's possible to construct and use an instance of Cache_Store on its own, however, the preferred method for working with the cache is to call Support_Resources::cache() (see Support_Resources).

There are currently three supported options that are not engine-specific. They are:

engine: The cache engine to use
ttl: Maximum time to live (in seconds)
expiration_check: The expiration check callback

The engine option specifies which of the available cache engines to use. Engine names are lower case. They correspond to a class name of Cache_Engine_camel_case_engine_name. For example, the "memory" engine is implemented by the class Cache_Engine_Memory. New engines may be added by creating new classes of the corresponding name. This package provides the following engines:

apc
file
memcache
memory

Note that the apc and memcache engines require the APC and Memcache extensions, respectively. If the corresponding extension is not installed, you will not be able to use that engine. See the documentation of the corresponding engine class for more information on what additional options the engine accepts.

The expiration_check option specifies a callback which, if provided, the get() method will use to check the validity of a cached data item before returning it. The callback is passed two parameters: a reference to the key value get() was called with, and a reference to the data value it is about to return. If the expiration check callback returns a boolean false value, the cached item is expired and will not be returned to get's caller.

The expiration check and data callback accepted by get() can be combined to more easily handle certain caching scenarios. As a simple example, let's say you're writing a blog application. To show off the caching functionality, let's imagine you've done some kind of fancy threading that takes a while to assemble, so you want to cache the result and only regenerate when you have to. You could choose to implement something like this:

class Post extends ActiveRecord_Base {
protected function init_class() {
$this->has_many('comments');
}
public function threaded_comments() {
$cache = Support_Resources::cache();
// use a cached value when possible
$data = $cache->get(array('post_comments'=>$this->id),
array('expiration_check'=>array($this, 'is_data_valid')),
array($this, 'rethread_comments'));
return $data['value'];
}
public function is_data_valid(&$key, &$data) {
if ($this->comments_updated_at > $data['updated_at'])
return false;
return true;
}
public function rethread_comments() {
$comments = $this->comments;
// do some complicated massaging of $comments...
return array('value=>$comments, 'updated_at'=>$this->comments_updated_at);
}
}

Admittedly, the example is a bit contrived. It does show usage of the two callback features, but in reality, if your own application is in charge of handling updates to comments on a post, it would be better to simply expire the cached item whenever new comments come in. However, the expiration_check callback can be very handy for when items may expire due to events outside of the control of your application. For example, when a configuration file is changed or if database entries may be created by other applications.

Configuration

Any of the supported options (with the exception of expiration_check) may also be specified in the config file as a way to control the defaults for cache storage. Cache configuration options are named the same as the options that may be passed to Cache_Store, but they must be inside the cache section. That is to say, the following configuration options are supported:

cache/engine
cache/ttl

Engine-specific options may also be specified this way (e.g. cache/cache_dir for the file engine).

Profiles may be created by placing the configuration options for that profile in cache/profiles/profile_name/options.... For example, you could create the following options:

cache/profiles/example/engine = memcache
cache/profiles/example/ttl = 3600
cache/profiles/example/host = localhost

You could then use that profile by passing just its name, as in:

$cache = Support_Resources::cache();
$cache->set('somekey', 'somevalue', 'example');

Located in /cache/lib/Cache/Store.php (line 122)

Variable Summary

mixed $engines

mixed $logger

Method Summary

Cache_Store __construct ()

void clear ([mixed $options = null])

void conditionally_remove ( $item, $mtime, &$key, &$data, $locking, $exLocked)

void engine ( $options)

void exists (mixed $key, [mixed $options = null])

void expire (mixed $key, [mixed $options = null])

mixed get (mixed $key, [mixed $options = null], [callback $callback = null])

boolean is_valid (Cache_ItemBase $item, $options, &$key, &$data, boolean $locking, $exLocked, array $option, mixed $key, mixed $data)

string key_value ( $key)

void logger ()

void set (mixed $key, mixed $data, [mixed $options = null])

array valid_options (mixed $options)

Variables

mixed $engines (line 124)

access: protected

mixed $logger (line 125)

access: protected

Methods

Constructor __construct (line 130)

Constructor

access: public

Cache_Store __construct ()

clear (line 306)

Remove all items from the cache.

This removes all items from a cache engine.

Options are:

engine: The cache engine to remove items from
Any engine-specific options

access: public

void clear ([mixed $options = null])

mixed $options: An array of options or a cache profile name

conditionally_remove (line 414)

Conditionally removes an item based on it being unchanged

access: protected

void conditionally_remove ( $item, $mtime, &$key, &$data, $locking, $exLocked)

$item
$mtime
&$key
&$data
$locking
$exLocked

engine (line 345)

Return the engine specified in the options.

The conversion from an engine name to an implementing class is "Cache_Engine_" . Support_Inflector::camelize($name).

access: protected

void engine ( $options)

$options

exists (line 246)

Test for the existence of key in the cache.

Options are:

engine: The cache engine to use
Any engine-specific options

access: public

void exists (mixed $key, [mixed $options = null])

mixed $key: The key set the value for
mixed $options: An array of options or a cache profile name

expire (line 276)

Remove key and its data from the cache.

Options are:

engine: The cache engine to use
Any engine-specific options

access: public

void expire (mixed $key, [mixed $options = null])

mixed $key: The key to remove
mixed $options: An array of options or a cache profile name

get (line 155)

Return the value for key.

If a callback is provided, it is called if key does not exist, and the value the callback returns is set in the cache and returned. This is useful not only for conditionally production the cache value, but if the underlying cache engine supports locking, this will also prevent multiple simultaneous attempts (in different processes or threads) to produce the value for the same key.

Options are:

engine: The cache engine to use
ttl: Maximum time to live (in seconds)
expiration_check: The expiration check callback
Any engine-specific options

access: public

mixed get (mixed $key, [mixed $options = null], [callback $callback = null])

mixed $key: The key to obtain the value for
mixed $options: An array of options or a cache profile name
callback $callback: The optional callback

is_valid (line 388)

Tests if an item is considered valid (has not yet expired)

access: protected

boolean is_valid (Cache_ItemBase $item, $options, &$key, &$data, boolean $locking, $exLocked, array $option, mixed $key, mixed $data)

Cache_ItemBase $item: The cache item object
array $option: Caching options
mixed $key: The key that was passed in
mixed $data: The data associated with the key
boolean $locking: Flag indicating whether or not the item is exclusively locked
$options
&$key
&$data
$exLocked

key_value (line 368)

Returns a clean key value

access: protected

string key_value ( $key)

$key

logger (line 438)

Return a logger instance

access: protected

void logger ()

set (line 217)

Store a value for key.

Options are:

engine: The cache engine to use
ttl: Maximum time to live (in seconds)
Any engine-specific options

access: public

void set (mixed $key, mixed $data, [mixed $options = null])

mixed $key: The key set the value for
mixed $data: The data to store
mixed $options: An array of options or a cache profile name

valid_options (line 324)

Return the correct set of options to use for a provided options argument

access: protected

array valid_options (mixed $options)

mixed $options: An array of options or a cache profile name