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.

Configuring Cache engines

You can configure Cache engines in your application's Config/cache.php file. A sample configuration would be:

Cache::config('shared', [
   'className' => 'Cake\Cache\Engine\ApcuEngine',
   'prefix' => 'my_app_'
]);

This would configure an APCu 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.

There are 7 built-in caching engines:

ApcuEngine - Uses the APCu object cache, one of the fastest caching engines.
ArrayEngine - Uses only memory to store all data, not actually a persistent engine. Can be useful in test or CLI environment.
FileEngine - Uses simple files to store content. Poor performance, but good for storing large objects, or things that are not IO sensitive. Well suited to development as it is an easy cache to inspect and manually flush.
MemcacheEngine - Uses the PECL::Memcache extension and Memcached for storage. Fast reads/writes, and benefits from memcache being distributed.
RedisEngine - Uses redis and php-redis extension to store cache data.
WincacheEngine - Uses Windows Cache Extension for PHP. Supports wincache 1.1.0 and higher. This engine is recommended to people deploying on windows with IIS.
XcacheEngine - Uses the Xcache extension, an alternative to APCu.

See Cache engine documentation for expected configuration keys.

Namespace: Cake\Cache
See: config/app.php for configuration settings

Property Summary

$_config protected static

array

Configuration sets.
$_dsnClassMap protected static

string[]

An array mapping url schemes to fully qualified caching engine class names.
$_enabled protected static

bool

Flag for tracking whether or not caching is enabled.
$_groups protected static

array

Group to Config mapping
$_registry protected static

Cake\Core\ObjectRegistry

Cache Registry used for creating and using cache adapters.

Method Summary

_buildEngine() protected static

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

Write data for key into a cache engine if it doesn't exist already.
clear() public static

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

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

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

This method can be used to define configuration adapters for an application or read existing configuration.
configured() public static

Returns an array containing the named configurations
decrement() public static

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

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

Delete many keys from the cache.
disable() public static

Disable caching.
drop() public static

Drops a constructed adapter.
dsnClassMap() public static deprecated

Returns or updates the DSN class map for this class.
enable() public static

Re-enable caching.
enabled() public static

Check whether or not caching is enabled.
engine() public static deprecated

Fetch the engine attached to a specific configuration name.
gc() public static deprecated

Garbage collection
getConfig() public static

Reads existing configuration.
getConfigOrFail() public static

Reads existing configuration for a specific key.
getDsnClassMap() public static

Returns the DSN class map for this class.
getRegistry() public static

Returns the Cache Registry instance used for creating and using cache adapters.
groupConfigs() public static

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

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

Parses a DSN into a valid connection configuration
pool() public static

Get a SimpleCacheEngine object for the named cache pool.
read() public static

Read a key from the cache.
readMany() public static

Read multiple keys from the cache.
registry() public static deprecated

Returns the Cache Registry instance used for creating and using cache adapters. Also allows for injecting of a new registry instance.
remember() public static

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

This method can be used to define configuration adapters for an application.
setDsnClassMap() public static

Updates the DSN class map for this class.
setRegistry() public static

Sets the Cache Registry instance used for creating and using cache adapters.
write() public static

Write data for key into cache.
writeMany() public static

Write data for many keys into cache.

Method Detail

_buildEngine() ¶ protected static

_buildEngine(string $name): void

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

void

Throws

InvalidArgumentException
When a cache engine cannot be created.

add() ¶ public static

add(string $key, mixed $value, string $config = 'default'): bool

Write data for key into a cache engine if it doesn't exist already.

Usage:

Writing to the active cache config:

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

Writing to a specific cache config:

Cache::add('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: Optional string configuration name to write to. Defaults to 'default'.

Returns

bool

clear() ¶ public static

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

Delete all keys from the cache.

Parameters

bool $check optional: if true will check expiration, otherwise delete all. This parameter will become a no-op value in 4.0 as it is deprecated.
string $config optional: name of the configuration to use. Defaults to 'default'

Returns

bool

clearAll() ¶ public static

clearAll(bool $check = false): array

Delete all keys from the cache from all configurations.

Parameters

bool $check optional: if true will check expiration, otherwise delete all. This parameter will become a no-op value in 4.0 as it is deprecated.

Returns

array

clearGroup() ¶ public static

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

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

Parameters

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

Returns

bool

config() ¶ public static

config(string|array $key, array|null $config = null): array|null

This method can be used to define configuration adapters for an application or read existing configuration.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Reading config data back:

Cache::config('default');

Setting a cache engine up.

Cache::config('default', $settings);

Injecting a constructed adapter in:

Cache::config('default', $instance);

Configure multiple adapters at once:

Cache::config($arrayOfConfig);

Parameters

string|array $key: The name of the configuration, or an array of multiple configs.
array|null $config optional: An array of name => configuration data for adapter.

Returns

array|null

Throws

BadMethodCallException
When trying to modify an existing config.

configured() ¶ public static

configured(): string[]

Returns an array containing the named configurations

Returns

string[]

decrement() ¶ public static

decrement(string $key, int $offset = 1, string $config = 'default'): int|false

Decrement a number under the key and return decremented value.

Parameters

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

Returns

int|false

delete() ¶ public static

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

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: name of the configuration to use. Defaults to 'default'

Returns

bool

deleteMany() ¶ public static

deleteMany(array $keys, string $config = 'default'): array

Delete many keys from the cache.

Usage:

Deleting multiple keys from the active cache configuration.

Cache::deleteMany(['my_data_1', 'my_data_2']);

Deleting from a specific cache configuration.

Cache::deleteMany(['my_data_1', 'my_data_2], 'long_term');

Parameters

array $keys: Array of cache keys to be deleted
string $config optional: name of the configuration to use. Defaults to 'default'

Returns

array

disable() ¶ public static

disable(): void

Disable caching.

When disabled all cache operations will return null.

Returns

void

drop() ¶ public static

drop(string $config): bool

Drops a constructed adapter.

If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.

If the implementing objects supports a $_registry object the named configuration will also be unloaded from the registry.

Parameters

string $config: An existing configuration you wish to remove.

Returns

bool

dsnClassMap() ¶ public static

dsnClassMap(string[]|null $map = null): string[]

Returns or updates the DSN class map for this class.

Parameters

string[]|null $map optional: Additions/edits to the class map to apply.

Returns

string[]

enable() ¶ public static

enable(): void

Re-enable caching.

If caching has been disabled with Cache::disable() this method will reverse that effect.

Returns

void

enabled() ¶ public static

enabled(): bool

Check whether or not caching is enabled.

Returns

bool

engine() ¶ public static

engine(string $config): Cake\Cache\CacheEngine

Fetch the engine attached to a specific configuration name.

If the cache engine & configuration are missing an error will be triggered.

Parameters

string $config: The configuration name you want an engine for.

Returns

Cake\Cache\CacheEngine

gc() ¶ public static

gc(string $config = 'default', int|null $expires = null): void

Garbage collection

Permanently remove all expired and deleted data

Parameters

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

Returns

void

getConfig() ¶ public static

getConfig(string $key): mixed|null

Reads existing configuration.

Parameters

string $key: The name of the configuration.

Returns

mixed|null

getConfigOrFail() ¶ public static

getConfigOrFail(string|null $key): mixed

Reads existing configuration for a specific key.

The config value for this key must exist, it can never be null.

Parameters

string|null $key: The name of the configuration.

Returns

mixed

Throws

InvalidArgumentException
If value does not exist.

getDsnClassMap() ¶ public static

getDsnClassMap(): string[]

Returns the DSN class map for this class.

Returns

string[]

getRegistry() ¶ public static

getRegistry(): Cake\Core\ObjectRegistry

Returns the Cache Registry instance used for creating and using cache adapters.

Returns

Cake\Core\ObjectRegistry

groupConfigs() ¶ public static

groupConfigs(string|null $group = null): array

Retrieve group names to config mapping.

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

$configs will equal to ['posts' => ['daily', 'weekly']] Calling this method will load all the configured engines.

Parameters

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

Returns

array

Throws

InvalidArgumentException

increment() ¶ public static

increment(string $key, int $offset = 1, string $config = 'default'): int|false

Increment a number under the key and return incremented value.

Parameters

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

Returns

int|false

parseDsn() ¶ public static

parseDsn(string $dsn): array

Parses a DSN into a valid connection configuration

This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:

$dsn = 'mysql://user:pass@localhost/database?';
$config = ConnectionManager::parseDsn($dsn);

$dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS';
$config = Log::parseDsn($dsn);

$dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null';
$config = Email::parseDsn($dsn);

$dsn = 'file:///?className=\My\Cache\Engine\FileEngine';
$config = Cache::parseDsn($dsn);

$dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/';
$config = Cache::parseDsn($dsn);

For all classes, the value of scheme is set as the value of both the className unless they have been otherwise specified.

Note that querystring arguments are also parsed and set as values in the returned configuration.

Parameters

string $dsn: The DSN string to convert to a configuration array

Returns

array

Throws

InvalidArgumentException
If not passed a string, or passed an invalid string

pool() ¶ public static

pool(string $config): Cake\Cache\SimpleCacheEngine

Get a SimpleCacheEngine object for the named cache pool.

Parameters

string $config: The name of the configured cache backend.

Returns

Cake\Cache\SimpleCacheEngine

read() ¶ public static

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

Read a key from the cache.

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: optional name of the configuration to use. Defaults to 'default'

Returns

mixed

readMany() ¶ public static

readMany(array $keys, string $config = 'default'): array

Read multiple keys from the cache.

Usage:

Reading multiple keys from the active cache configuration.

Cache::readMany(['my_data_1', 'my_data_2]);

Reading from a specific cache configuration.

Cache::readMany(['my_data_1', 'my_data_2], 'long_term');

Parameters

array $keys: an array of keys to fetch from the cache
string $config optional: optional name of the configuration to use. Defaults to 'default'

Returns

array

registry() ¶ public static

registry(Cake\Core\ObjectRegistry|null $registry = null): Cake\Core\ObjectRegistry

Returns the Cache Registry instance used for creating and using cache adapters. Also allows for injecting of a new registry instance.

Parameters

Cake\Core\ObjectRegistry|null $registry optional: Injectable registry object.

Returns

Cake\Core\ObjectRegistry

remember() ¶ public static

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

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 Table object:

$results = Cache::remember('all_articles', function () {
     return $this->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: The cache configuration to use for this operation. Defaults to default.

Returns

mixed

setConfig() ¶ public static

setConfig(string|array $key, array|object|null $config = null): void

This method can be used to define configuration adapters for an application.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Setting a cache engine up.

Cache::setConfig('default', $settings);

Injecting a constructed adapter in:

Cache::setConfig('default', $instance);

Configure multiple adapters at once:

Cache::setConfig($arrayOfConfig);

Parameters

string|array $key: The name of the configuration, or an array of multiple configs.
array|object|null $config optional: An array of name => configuration data for adapter.

Returns

void

Throws

BadMethodCallException
When trying to modify an existing config.
LogicException
When trying to store an invalid structured config array.

setDsnClassMap() ¶ public static

setDsnClassMap(string[] $map): void

Updates the DSN class map for this class.

Parameters

string[] $map: Additions/edits to the class map to apply.

Returns

void

setRegistry() ¶ public static

setRegistry(Cake\Core\ObjectRegistry $registry): void

Sets the Cache Registry instance used for creating and using cache adapters.

Also allows for injecting of a new registry instance.

Parameters

Cake\Core\ObjectRegistry $registry: Injectable registry object.

Returns

void

write() ¶ public static

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

Write data for key into cache.

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: Optional string configuration name to write to. Defaults to 'default'

Returns

bool

writeMany() ¶ public static

writeMany(array $data, string $config = 'default'): array

Write data for many keys into cache.

Usage:

Writing to the active cache config:

Cache::writeMany(['cached_data_1' => 'data 1', 'cached_data_2' => 'data 2']);

Writing to a specific cache config:

Cache::writeMany(['cached_data_1' => 'data 1', 'cached_data_2' => 'data 2'], 'long_term');

Parameters

array $data: An array of data to be stored in the cache
string $config optional: Optional string configuration name to write to. Defaults to 'default'

Returns

array

Throws

RuntimeException

Property Detail

`$_config` ¶ protected static

Configuration sets.

Type

array

`$_dsnClassMap` ¶ protected static

An array mapping url schemes to fully qualified caching engine class names.

Type

string[]

`$_enabled` ¶ protected static

Flag for tracking whether or not caching is enabled.

Type

bool

`$_groups` ¶ protected static

Group to Config mapping

Type

array

`$_registry` ¶ protected static

Cache Registry used for creating and using cache adapters.

Type

Cake\Core\ObjectRegistry

Namespaces

Class Cache

Configuring Cache engines

Property Summary

Method Summary

_buildEngine() protected static

add() public static

clear() public static

clearAll() public static

clearGroup() public static

config() public static deprecated

configured() public static

decrement() public static

delete() public static

deleteMany() public static

disable() public static

drop() public static

dsnClassMap() public static deprecated

enable() public static

enabled() public static

engine() public static deprecated

gc() public static deprecated

getConfig() public static

getConfigOrFail() public static

getDsnClassMap() public static

getRegistry() public static

groupConfigs() public static

increment() public static

parseDsn() public static

pool() public static

read() public static

readMany() public static

registry() public static deprecated

remember() public static

setConfig() public static

setDsnClassMap() public static

setRegistry() public static

write() public static

writeMany() public static

Method Detail

_buildEngine() ¶ protected static

Parameters

Returns

Throws

add() ¶ public static

Usage:

Parameters

Returns

clear() ¶ public static

Parameters

Returns

clearAll() ¶ public static

Parameters

Returns

clearGroup() ¶ public static

Parameters

Returns

config() ¶ public static

Usage

Parameters

Returns

Throws

configured() ¶ public static

Returns

decrement() ¶ public static

Parameters

Returns

delete() ¶ public static

Usage:

Parameters

Returns

deleteMany() ¶ public static

Usage:

Parameters

Returns

disable() ¶ public static

Returns

drop() ¶ public static

Parameters

Returns