Class Cache

Cache provides a consistent interface to Caching in your application. It allows you to use several different Cache engines, without coupling your application to a specific implementation. It also allows you to change out cache storage or configuration without effecting the rest of your application.

You can configure Cache engines in your application's bootstrap.php file. A sample configuration would be

Cache::config('shared', array(
    'engine' => 'Apc',
    'prefix' => 'my_app_'
 ));

This would configure an APC cache engine to the 'shared' alias. You could then read and write to that cache alias by using it for the $config parameter in the various Cache methods. In general all Cache operations are supported by all cache engines. However, Cache::increment() and Cache::decrement() are not supported by File caching.

Package: Cake\Cache
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Cache/Cache.php

Properties summary

$_config protected static

array

Cache configuration stack Keeps the permanent/default settings for each cache engine. These settings are used to reset the engines after temporary modification.
$_engines protected static

array

Engine instances keyed by configuration name.
$_groups protected static

array

Group to Config mapping
$_reset protected static

array

Whether to reset the settings with the next call to Cache::set();

Method Summary

_buildEngine() protected static

Finds and builds the instance of the required engine class.
clear() public static

Delete all keys from the cache.
clearGroup() public static

Delete all keys from the cache belonging to the same group.
config() public static

Set the cache configuration to use. config() can both create new configurations, return the settings for already configured configurations.
configured() public static

Returns an array containing the currently configured Cache settings.
decrement() public static

Decrement a number under the key and return decremented value.
delete() public static

Delete a key from the cache.
drop() public static

Drops a cache engine. Deletes the cache configuration information If the deleted configuration is the last configuration using a certain engine, the Engine instance is also unset.
gc() public static

Garbage collection
groupConfigs() public static

Retrieve group names to config mapping.
increment() public static

Increment a number under the key and return incremented value.
isInitialized() public static

Check if Cache has initialized a working config for the given name.
read() public static

Read a key from a cache config.
remember() public static

Provides the ability to easily do read-through caching.
set() public static

Temporarily change the settings on a cache config. The settings will persist for the next write operation (write, decrement, increment, clear). Any reads that are done before the write, will use the modified settings. If $settings is empty, the settings will be reset to the original configuration.
settings() public static

Return the settings for the named cache engine.
write() public static

Write data for key into a cache engine.

Method Detail

_buildEngine() protected static ¶

_buildEngine( string $name )

Finds and builds the instance of the required engine class.

Parameters

string $name: Name of the config array that needs an engine instance built

Returns

boolean

Throws

CacheException

clear() public static ¶

clear( boolean $check = false , string $config = 'default' )

Delete all keys from the cache.

Parameters

boolean $check optional false: if true will check expiration, otherwise delete all
string $config optional 'default': name of the configuration to use. Defaults to 'default'

Returns

boolean
True if the cache was successfully cleared, false otherwise

clearGroup() public static ¶

clearGroup( string $group , string $config = 'default' )

Delete all keys from the cache belonging to the same group.

Parameters

string $group: name of the group to be cleared
string $config optional 'default': name of the configuration to use. Defaults to 'default'

Returns

boolean
True if the cache group was successfully cleared, false otherwise

config() public static ¶

config( string $name = null , array $settings = array() )

Set the cache configuration to use. config() can both create new configurations, return the settings for already configured configurations.

To create a new configuration, or to modify an existing configuration permanently:

Cache::config('my_config', array('engine' => 'File', 'path' => TMP));

If you need to modify a configuration temporarily, use Cache::set(). To get the settings for a configuration:

Cache::config('default');

There are 5 built-in caching engines:

FileEngine - Uses simple files to store content. Poor performance, but good for storing large objects, or things that are not IO sensitive.
ApcEngine - Uses the APC object cache, one of the fastest caching engines.
MemcacheEngine - Uses the PECL::Memcache extension and Memcached for storage. Fast reads/writes, and benefits from memcache being distributed.
XcacheEngine - Uses the Xcache extension, an alternative to APC.
WincacheEngine - Uses Windows Cache Extension for PHP. Supports wincache 1.1.0 and higher.

The following keys are used in core cache engines:

duration Specify how long items in this cache configuration last.
groups List of groups or 'tags' associated to every key stored in this config. handy for deleting a complete group from cache.
prefix Prefix appended to all entries. Good for when you need to share a keyspace with either another cache config or another application.
probability Probability of hitting a cache gc cleanup. Setting to 0 will disable cache::gc from ever being called automatically.
`servers' Used by memcache. Give the address of the memcached servers to use.
compress Used by memcache. Enables memcache's compressed format.
serialize Used by FileCache. Should cache objects be serialized first.
path Used by FileCache. Path to where cachefiles should be saved.
lock Used by FileCache. Should files be locked before writing to them?
user Used by Xcache. Username for XCache
password Used by Xcache/Redis. Password for XCache/Redis

Parameters

string $name optional null: Name of the configuration
array $settings optional array(): Optional associative array of settings passed to the engine

Returns

array
array(engine, settings) on success, false on failure

Throws

CacheException

See

app/Config/core.php for configuration settings

configured() public static ¶

configured( )

Returns an array containing the currently configured Cache settings.

Returns

array
Array of configured Cache config names.

decrement() public static ¶

decrement( string $key , integer $offset = 1 , string $config = 'default' )

Decrement a number under the key and return decremented value.

Parameters

string $key: Identifier for the data
integer $offset optional 1: How much to subtract
string $config optional 'default': Optional string configuration name. Defaults to 'default'

Returns

mixed

new value, or false if the data doesn't exist, is not integer, or if there was an error fetching it

delete() public static ¶

delete( string $key , string $config = 'default' )

Delete a key from the cache.

Usage:

Deleting from the active cache configuration.

Cache::delete('my_data');

Deleting from a specific cache configuration.

Cache::delete('my_data', 'long_term');

Parameters

string $key: Identifier for the data
string $config optional 'default': name of the configuration to use. Defaults to 'default'

Returns

boolean
True if the value was successfully deleted, false if it didn't exist or couldn't be removed

drop() public static ¶

drop( string $name )

Drops a cache engine. Deletes the cache configuration information If the deleted configuration is the last configuration using a certain engine, the Engine instance is also unset.

Parameters

string $name: A currently configured cache config you wish to remove.

Returns

boolean
success of the removal, returns false when the config does not exist.

gc() public static ¶

gc( string $config = 'default' , integer $expires = null )

Garbage collection

Permanently remove all expired and deleted data

Parameters

string $config optional 'default': [optional] The config name you wish to have garbage collected. Defaults to 'default'
integer $expires optional null: [optional] An expires timestamp. Defaults to NULL

groupConfigs() public static ¶

groupConfigs( string $group = null )

Retrieve group names to config mapping.

Cache::config('daily', array(
    'duration' => '1 day', 'groups' => array('posts')
));
Cache::config('weekly', array(
    'duration' => '1 week', 'groups' => array('posts', 'archive')
));
$configs = Cache::groupConfigs('posts');

$config will equal to array('posts' => array('daily', 'weekly'))

Parameters

string $group optional null: group name or null to retrieve all group mappings

Returns

array
map of group and all configuration that has the same group

Throws

CacheException

increment() public static ¶

increment( string $key , integer $offset = 1 , string $config = 'default' )

Increment a number under the key and return incremented value.

Parameters

string $key: Identifier for the data
integer $offset optional 1: How much to add
string $config optional 'default': Optional string configuration name. Defaults to 'default'

Returns

mixed

new value, or false if the data doesn't exist, is not integer, or if there was an error fetching it.

isInitialized() public static ¶

isInitialized( string $config = 'default' )

Check if Cache has initialized a working config for the given name.

Parameters

string $config optional 'default': name of the configuration to use. Defaults to 'default'

Returns

boolean
Whether or not the config name has been initialized.

read() public static ¶

read( string $key , string $config = 'default' )

Read a key from a cache config.

Usage:

Reading from the active cache configuration.

Cache::read('my_data');

Reading from a specific cache configuration.

Cache::read('my_data', 'long_term');

Parameters

string $key: Identifier for the data
string $config optional 'default': optional name of the configuration to use. Defaults to 'default'

Returns

mixed
The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it

remember() public static ¶

remember( string $key , callable $callable , string $config = 'default' )

Provides the ability to easily do read-through caching.

When called if the $key is not set in $config, the $callable function will be invoked. The results will then be stored into the cache config at key.

Examples:

Using a Closure to provide data, assume $this is a Model:

$model = $this;
$results = Cache::remember('all_articles', function() use ($model) {
     return $model->find('all');
});

Parameters

string $key: The cache key to read/store data at.
callable $callable: The callable that provides data in the case when the cache key is empty. Can be any callable type supported by your PHP.
string $config optional 'default': The cache configuration to use for this operation. Defaults to default.

Returns

mixed
The results of the callable or unserialized results.

set() public static ¶

set( string|array $settings = array() , string $value = null , string $config = 'default' )

Temporarily change the settings on a cache config. The settings will persist for the next write operation (write, decrement, increment, clear). Any reads that are done before the write, will use the modified settings. If $settings is empty, the settings will be reset to the original configuration.

Can be called with 2 or 3 parameters. To set multiple values at once.

Cache::set(array('duration' => '+30 minutes'), 'my_config');

Or to set one value.

Cache::set('duration', '+30 minutes', 'my_config');

To reset a config back to the originally configured values.

Cache::set(null, 'my_config');

Parameters

string|array $settings optional array(): Optional string for simple name-value pair or array
string $value optional null: Optional for a simple name-value pair
string $config optional 'default': The configuration name you are changing. Defaults to 'default'

Returns

array
Array of settings.

settings() public static ¶

settings( string $name = 'default' )

Return the settings for the named cache engine.

Parameters

string $name optional 'default': Name of the configuration to get settings for. Defaults to 'default'

Returns

array
list of settings for this engine

See

Cache::config()

write() public static ¶

write( string $key , mixed $value , string $config = 'default' )

Write data for key into a cache engine.

Usage:

Writing to the active cache config:

Cache::write('cached_data', $data);

Writing to a specific cache config:

Cache::write('cached_data', $data, 'long_term');

Parameters

string $key: Identifier for the data
mixed $value: Data to be cached - anything except a resource
string $config optional 'default': Optional string configuration name to write to. Defaults to 'default'

Returns

boolean
True if the data was successfully cached, false on failure

Properties detail

`$_config` ¶

protected static array

Cache configuration stack Keeps the permanent/default settings for each cache engine. These settings are used to reset the engines after temporary modification.

array()

`$_engines` ¶

protected static array

Engine instances keyed by configuration name.

array()

`$_groups` ¶

protected static array

Group to Config mapping

array()

`$_reset` ¶

protected static array

Whether to reset the settings with the next call to Cache::set();

false

Packages

Classes

Class Cache

Properties summary

Method Summary

_buildEngine() protected static

clear() public static

clearGroup() public static

config() public static

configured() public static

decrement() public static

delete() public static

drop() public static

gc() public static

groupConfigs() public static

increment() public static

isInitialized() public static

read() public static

remember() public static

set() public static

settings() public static

write() public static

Method Detail

_buildEngine() protected static ¶

Parameters

Returns

Throws

clear() public static ¶

Parameters

Returns

clearGroup() public static ¶

Parameters

Returns

config() public static ¶

Parameters

Returns

Throws

See

configured() public static ¶

Returns

decrement() public static ¶

Parameters

Returns

delete() public static ¶

Usage:

Parameters

Returns

drop() public static ¶

Parameters

Returns

gc() public static ¶

Parameters

groupConfigs() public static ¶

Parameters

Returns

Throws

increment() public static ¶

Parameters

Returns

isInitialized() public static ¶

Parameters

Returns

read() public static ¶

Usage:

Parameters

Returns

remember() public static ¶

Parameters

Returns

set() public static ¶

Parameters

Returns

settings() public static ¶

Parameters

Returns

See

write() public static ¶

Usage:

Parameters

Returns

`$_config` ¶

`$_engines` ¶

`$_groups` ¶

`$_reset` ¶