Cache (class)
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\ApcEngine', '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.
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. Well suited to development as it is an easy cache to inspect and manually flush. -
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. This engine is recommended to people deploying on windows with IIS. -
RedisEngine
- Uses redis and php-redis extension to store cache data.
See Cache engine documentation for expected configuration keys.
- Cake\Cache\Cache uses Cake\Core\StaticConfigTrait
See: config/app.php for configuration settings
Param: string $name Name of the configuration
Param: array $config Optional associative array of settings passed to the engine
Return:
array
[engine, settings] on success, false on failure
Located at Cache/Cache.php
Method Detail
_buildEnginesource 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
InvalidArgumentException
When a cache engine cannot be created.
addsource public static
add( string $key , mixed $value , string $config 'default' )
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 'default' - Optional string configuration name to write to. Defaults to 'default'.
Returns
boolean
True if the data was successfully cached, false on failure. Or if the key existed already.
clearsource 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
clearGroupsource 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
decrementsource 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
deletesource 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
deleteManysource public static
deleteMany( array $keys , string $config 'default' )
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 'default' - name of the configuration to use. Defaults to 'default'
Returns
array
of boolean values that are true if the value was successfully deleted, false if it didn't exist or couldn't be removed
disablesource public static
disable( )
Disable caching.
When disabled all cache operations will return null.
enablesource public static
enable( )
Re-enable caching.
If caching has been disabled with Cache::disable() this method will reverse that effect.
enginesource public static
engine( string $config )
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
When caching is disabled a null engine will be returned.
gcsource public static
gc( string $config 'default' , integer|null $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|null
$expires
optional null - [optional] An expires timestamp. Defaults to NULL
groupConfigssource public static
groupConfigs( string|null $group null )
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 null - group name or null to retrieve all group mappings
Returns
array
map of group and all configuration that has the same group
Throws
InvalidArgumentException
\InvalidArgumentException
incrementsource 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.
readsource public static
read( string $key , string $config 'default' )
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 '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
readManysource public static
readMany( array $keys , string $config 'default' )
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 'default' - optional name of the configuration to use. Defaults to 'default'
Returns
array
An array containing, for each of the given $keys, the cached data or false if cached data could not be retrieved.
registrysource public static
registry( Cake\Core\ObjectRegistry $registry null )
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
$registry
optional null - Injectable registry object.
Returns
Cake\Core\ObjectRegistry
\Cake\Core\ObjectRegistry
remembersource 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 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 'default' - 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
writesource public static
write( string $key , mixed $value , string $config 'default' )
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 'default' - Optional string configuration name to write to. Defaults to 'default'
Returns
boolean
True if the data was successfully cached, false on failure
writeManysource public static
writeMany( array $data , string $config 'default' )
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 'default' - Optional string configuration name to write to. Defaults to 'default'
Returns
array
of bools for each key provided, indicating true for success or false for fail
Throws
RuntimeException
\RuntimeException
Methods used from Cake\Core\StaticConfigTrait
configsource public static
config( string|array $key , array $config 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
$config
optional null - An array of name => configuration data for adapter.
Returns
array|null
Null when adding configuration or an array of configuration data when reading.
Throws
BadMethodCallException
When trying to modify an existing config.
configuredsource public static
configured( )
Returns an array containing the named configurations
Returns
array
Array of configurations.
dropsource 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
boolean
Success of the removal, returns false when the config does not exist.
dsnClassMapsource public static
dsnClassMap( array $map null )
Returns or updates the DSN class map for this class
Parameters
- array
$map
optional null - Additions/edits to the class map to apply
Returns
array
array
parseDsnsource 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: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
The configuration array to be stored after parsing the DSN
Throws
InvalidArgumentException
If not passed a string
Properties summary
Properties used from Cake\Core\StaticConfigTrait
© 2005–2016 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.
http://api.cakephp.org/3.1/class-Cake.Cache.Cache.html