W3cubDocs

/CakePHP 4.1

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::class,
   '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

Properties 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\Cache\CacheRegistry|null

    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.

  • 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.

  • enable() public static

    Re-enable caching.

  • enabled() public static

    Check whether or not caching is enabled.

  • engine() public static

    Get a cache engine object for the named cache config.

  • 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.

  • 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)

Finds and builds the instance of the required engine class.

Parameters

string $name

Name of the config array that needs an engine instance built

Throws

Cake\Cache\InvalidArgumentException
When a cache engine cannot be created.
RuntimeException
If loading of the engine failed.

add() public static

add(string $key, mixed $value, string $config)

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

True if the data was successfully cached, false on failure. Or if the key existed already.

clear() public static

clear(string $config)

Delete all keys from the cache.

Parameters

string $config optional

name of the configuration to use. Defaults to 'default'

Returns

bool

True if the cache was successfully cleared, false otherwise

clearAll() public static

clearAll()

Delete all keys from the cache from all configurations.

Returns

bool[]

Status code. For each configuration, it reports the status of the operation

clearGroup() public static

clearGroup(string $group, string $config)

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

True if the cache group was successfully cleared, false otherwise

configured() public static

configured()

Returns an array containing the named configurations

Returns

string[]

Array of configurations.

decrement() public static

decrement(string $key, int $offset, string $config)

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

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

Throws

Cake\Cache\InvalidArgumentException
when offset < 0

delete() public static

delete(string $key, string $config)

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

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

deleteMany() public static

deleteMany(iterable $keys, string $config)

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

iterable $keys

Array or Traversable of cache keys to be deleted

string $config optional

name of the configuration to use. Defaults to 'default'

Returns

bool

True on success, false on failure.

Throws

Cake\Cache\InvalidArgumentException

disable() public static

disable()

Disable caching.

When disabled all cache operations will return null.

drop() public static

drop(string $config)

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

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

enable() public static

enable()

Re-enable caching.

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

enabled() public static

enabled()

Check whether or not caching is enabled.

Returns

bool

engine() public static

engine(string $config)

Get a cache engine object for the named cache config.

Parameters

string $config

The name of the configured cache backend.

Returns

\Psr\SimpleCache\CacheInterface&\Cake\Cache\CacheEngineInterface

getConfig() public static

getConfig(string $key)

Reads existing configuration.

Parameters

string $key

The name of the configuration.

Returns

mixed|null

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public static

getConfigOrFail(string $key)

Reads existing configuration for a specific key.

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

Parameters

string $key

The name of the configuration.

Returns

mixed

Configuration data at the named key.

Throws

InvalidArgumentException
If value does not exist.

getDsnClassMap() public static

getDsnClassMap()

Returns the DSN class map for this class.

Returns

string[]

getRegistry() public static

getRegistry()

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

Returns

\Cake\Cache\CacheRegistry

groupConfigs() public static

groupConfigs(?string $group)

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

map of group and all configuration that has the same group

Throws

Cake\Cache\InvalidArgumentException

increment() public static

increment(string $key, int $offset, string $config)

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

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

Throws

Cake\Cache\InvalidArgumentException
When offset < 0

parseDsn() public static

parseDsn(string $dsn)

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:[email protected]/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:[email protected]: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

The configuration array to be stored after parsing the DSN

Throws

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

pool() public static

pool(string $config)

Get a SimpleCacheEngine object for the named cache pool.

Parameters

string $config

The name of the configured cache backend.

Returns

\Psr\SimpleCache\CacheInterface&\Cake\Cache\CacheEngineInterface

read() public static

read(string $key, string $config)

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

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

readMany() public static

readMany(iterable $keys, string $config)

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

iterable $keys

An array or Traversable of keys to fetch from the cache

string $config optional

optional name of the configuration to use. Defaults to 'default'

Returns

iterable

An array containing, for each of the given $keys, the cached data or false if cached data could not be retrieved.

Throws

Cake\Cache\InvalidArgumentException

remember() public static

remember(string $key, callable $callable, string $config)

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

If the key is found: the cached data, false if the data missing/expired, or an error. If the key is not found: boolean of the success of the write

setConfig() public static

setConfig(mixed $key, mixed $config)

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.

Throws

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

setDsnClassMap() public static

setDsnClassMap(array $map)

Updates the DSN class map for this class.

Parameters

string[] $map

Additions/edits to the class map to apply.

setRegistry() public static

setRegistry(\Cake\Cache\CacheRegistry $registry)

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

Also allows for injecting of a new registry instance.

Parameters

\Cake\Cache\CacheRegistry $registry

Injectable registry object.

write() public static

write(string $key, mixed $value, string $config)

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

True if the data was successfully cached, false on failure

writeMany() public static

writeMany(iterable $data, string $config)

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

iterable $data

An array or Traversable of data to be stored in the cache

string $config optional

Optional string configuration name to write to. Defaults to 'default'

Returns

bool

True on success, false on failure

Throws

Cake\Cache\InvalidArgumentException

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\Cache\CacheRegistry|null

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Cache.Cache.html