PHP Class yii\caching\Cache

A data item can be stored in the cache by calling Cache::set and be retrieved back later (in the same or different request) by Cache::get. In both operations, a key identifying the data item is required. An expiration time and/or a [[Dependency|dependency]] can also be specified when calling Cache::set. If the data item expires or the dependency changes at the time of calling Cache::get, the cache will return no data. A typical usage pattern of cache is like the following: php $key = 'demo'; $data = $cache->get($key); if ($data === false) { ...generate $data here... $cache->set($key, $data, $duration, $dependency); } Because Cache implements the [[\ArrayAccess]] interface, it can be used like an array. For example, php $cache['foo'] = 'some data'; echo $cache['foo']; Derived classes should implement the following methods which do the actual cache storage operations: - Cache::getValue: retrieve the value with a key (if any) from cache - Cache::setValue: store the value with a key into cache - Cache::addValue: store the value only if the cache does not have this key before - Cache::deleteValue: delete the value with the specified key from cache - Cache::flushValues: delete all values from cache
Since: 2.0
Author: Qiang Xue ([email protected])
Inheritance: extends yii\base\Component, implements ArrayAccess
显示文件 Open project: yiisoft/yii2 Class Usage Examples

Public Properties

Property Type Description
$defaultDuration default duration in seconds before a cache entry will expire. Default value is 0, meaning infinity. This value is used by Cache::set if the duration is not explicitly given.
$keyPrefix a string prefixed to every cache key so that it is unique globally in the whole cache storage. It is recommended that you set a unique cache key prefix for each application if the same cache storage is being used by different applications. To ensure interoperability, only alphanumeric characters should be used.
$serializer the functions used to serialize and unserialize cached data. Defaults to null, meaning using the default PHP serialize() and unserialize() functions. If you want to use some more efficient serializer (e.g. igbinary), you may configure this property with a two-element array. The first element specifies the serialization function, and the second the deserialization function. If this property is set false, data will be directly sent to and retrieved from the underlying cache component without any serialization or deserialization. You should not turn off serialization if you are using [[Dependency|cache dependency]], because it relies on data serialization. Also, some implementations of the cache can not correctly save and retrieve data different from a string type.

Public Methods

Method Description
add ( mixed $key, mixed $value, integer $duration, yii\caching\Dependency $dependency = null ) : boolean Stores a value identified by a key into cache if the cache does not contain this key.
buildKey ( mixed $key ) : string Builds a normalized cache key from a given key.
delete ( mixed $key ) : boolean Deletes a value with the specified key from cache
exists ( mixed $key ) : boolean Checks whether a specified key exists in the cache.
flush ( ) : boolean Deletes all values from cache.
get ( mixed $key ) : mixed Retrieves a value from cache with a specified key.
madd ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array Stores multiple items in cache. Each item contains a value identified by a key.
mget ( string[] $keys ) : array Retrieves multiple values from cache with the specified keys.
mset ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array Stores multiple items in cache. Each item contains a value identified by a key.
multiAdd ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array Stores multiple items in cache. Each item contains a value identified by a key.
multiGet ( string[] $keys ) : array Retrieves multiple values from cache with the specified keys.
multiSet ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array Stores multiple items in cache. Each item contains a value identified by a key.
offsetExists ( string $key ) : boolean Returns whether there is a cache entry with a specified key.
offsetGet ( string $key ) : mixed Retrieves the value from cache with a specified key.
offsetSet ( string $key, mixed $value ) Stores the value identified by a key into cache.
offsetUnset ( string $key ) Deletes the value with the specified key from cache This method is required by the interface [[\ArrayAccess]].
set ( mixed $key, mixed $value, integer $duration = null, yii\caching\Dependency $dependency = null ) : boolean Stores a value identified by a key into cache.

Protected Methods

Method Description
addValue ( string $key, mixed $value, integer $duration ) : boolean Stores a value identified by a key into cache if the cache does not contain this key.
addValues ( array $data, integer $duration ) : array Adds multiple key-value pairs to cache.
deleteValue ( string $key ) : boolean Deletes a value with the specified key from cache This method should be implemented by child classes to delete the data from actual cache storage.
flushValues ( ) : boolean Deletes all values from cache.
getValue ( string $key ) : mixed | false Retrieves a value from cache with a specified key.
getValues ( array $keys ) : array Retrieves multiple values from cache with the specified keys.
setValue ( string $key, mixed $value, integer $duration ) : boolean Stores a value identified by a key in cache.
setValues ( array $data, integer $duration ) : array Stores multiple key-value pairs in cache.

Method Details

add() public method

Nothing will be done if the cache already contains the key.
public add ( mixed $key, mixed $value, integer $duration, yii\caching\Dependency $dependency = null ) : boolean
$key mixed a key identifying the value to be cached. This can be a simple string or a complex data structure consisting of factors representing the key.
$value mixed the value to be cached
$duration integer the number of seconds in which the cached value will expire. 0 means never expire.
$dependency yii\caching\Dependency dependency of the cached item. If the dependency changes, the corresponding value in the cache will be invalidated when it is fetched via [[get()]]. This parameter is ignored if [[serializer]] is false.
return boolean whether the value is successfully stored into cache

addValue() abstract protected method

This method should be implemented by child classes to store the data in specific cache storage.
abstract protected addValue ( string $key, mixed $value, integer $duration ) : boolean
$key string the key identifying the value to be cached
$value mixed the value to be cached. Most often it's a string. If you have disabled [[serializer]], it could be something else.
$duration integer the number of seconds in which the cached value will expire. 0 means never expire.
return boolean true if the value is successfully stored into cache, false otherwise

addValues() protected method

The default implementation calls Cache::addValue multiple times add values one by one. If the underlying cache storage supports multi-add, this method should be overridden to exploit that feature.
protected addValues ( array $data, integer $duration ) : array
$data array array where key corresponds to cache key while value is the value stored.
$duration integer the number of seconds in which the cached values will expire. 0 means never expire.
return array array of failed keys

buildKey() public method

If the given key is a string containing alphanumeric characters only and no more than 32 characters, then the key will be returned back prefixed with [[keyPrefix]]. Otherwise, a normalized key is generated by serializing the given key, applying MD5 hashing, and prefixing with [[keyPrefix]].
public buildKey ( mixed $key ) : string
$key mixed the key to be normalized
return string the generated cache key

delete() public method

Deletes a value with the specified key from cache
public delete ( mixed $key ) : boolean
$key mixed a key identifying the value to be deleted from cache. This can be a simple string or a complex data structure consisting of factors representing the key.
return boolean if no error happens during deletion

deleteValue() abstract protected method

Deletes a value with the specified key from cache This method should be implemented by child classes to delete the data from actual cache storage.
abstract protected deleteValue ( string $key ) : boolean
$key string the key of the value to be deleted
return boolean if no error happens during deletion

exists() public method

This can be faster than getting the value from the cache if the data is big. In case a cache does not support this feature natively, this method will try to simulate it but has no performance improvement over getting it. Note that this method does not check whether the dependency associated with the cached data, if there is any, has changed. So a call to [[get]] may return false while exists returns true.
public exists ( mixed $key ) : boolean
$key mixed a key identifying the cached value. This can be a simple string or a complex data structure consisting of factors representing the key.
return boolean true if a value exists in cache, false if the value is not in the cache or expired.

flush() public method

Be careful of performing this operation if the cache is shared among multiple applications.
public flush ( ) : boolean
return boolean whether the flush operation was successful.

flushValues() abstract protected method

Child classes may implement this method to realize the flush operation.
abstract protected flushValues ( ) : boolean
return boolean whether the flush operation was successful.

get() public method

Retrieves a value from cache with a specified key.
public get ( mixed $key ) : mixed
$key mixed a key identifying the cached value. This can be a simple string or a complex data structure consisting of factors representing the key.
return mixed the value stored in cache, false if the value is not in the cache, expired, or the dependency associated with the cached data has changed.

getValue() abstract protected method

This method should be implemented by child classes to retrieve the data from specific cache storage.
abstract protected getValue ( string $key ) : mixed | false
$key string a unique key identifying the cached value
return mixed | false the value stored in cache, false if the value is not in the cache or expired. Most often value is a string. If you have disabled [[serializer]], it could be something else.

getValues() protected method

The default implementation calls Cache::getValue multiple times to retrieve the cached values one by one. If the underlying cache storage supports multiget, this method should be overridden to exploit that feature.
protected getValues ( array $keys ) : array
$keys array a list of keys identifying the cached values
return array a list of cached values indexed by the keys

madd() public method

If the cache already contains such a key, the existing value and expiration time will be preserved.
Deprecation: This method is an alias for [[multiAdd()]] and will be removed in 2.1.0.
public madd ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array
$items array the items to be cached, as key-value pairs.
$duration integer default number of seconds in which the cached values will expire. 0 means never expire.
$dependency yii\caching\Dependency dependency of the cached items. If the dependency changes, the corresponding values in the cache will be invalidated when it is fetched via [[get()]]. This parameter is ignored if [[serializer]] is false.
return array array of failed keys

mget() public method

Some caches (such as memcache, apc) allow retrieving multiple cached values at the same time, which may improve the performance. In case a cache does not support this feature natively, this method will try to simulate it.
Deprecation: This method is an alias for [[multiGet()]] and will be removed in 2.1.0.
public mget ( string[] $keys ) : array
$keys string[] list of string keys identifying the cached values
return array list of cached values corresponding to the specified keys. The array is returned in terms of (key, value) pairs. If a value is not cached or expired, the corresponding array value will be false.

mset() public method

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.
Deprecation: This method is an alias for [[multiSet()]] and will be removed in 2.1.0.
public mset ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array
$items array the items to be cached, as key-value pairs.
$duration integer default number of seconds in which the cached values will expire. 0 means never expire.
$dependency yii\caching\Dependency dependency of the cached items. If the dependency changes, the corresponding values in the cache will be invalidated when it is fetched via [[get()]]. This parameter is ignored if [[serializer]] is false.
return array array of failed keys

multiAdd() public method

If the cache already contains such a key, the existing value and expiration time will be preserved.
Since: 2.0.7
public multiAdd ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array
$items array the items to be cached, as key-value pairs.
$duration integer default number of seconds in which the cached values will expire. 0 means never expire.
$dependency yii\caching\Dependency dependency of the cached items. If the dependency changes, the corresponding values in the cache will be invalidated when it is fetched via [[get()]]. This parameter is ignored if [[serializer]] is false.
return array array of failed keys

multiGet() public method

Some caches (such as memcache, apc) allow retrieving multiple cached values at the same time, which may improve the performance. In case a cache does not support this feature natively, this method will try to simulate it.
Since: 2.0.7
public multiGet ( string[] $keys ) : array
$keys string[] list of string keys identifying the cached values
return array list of cached values corresponding to the specified keys. The array is returned in terms of (key, value) pairs. If a value is not cached or expired, the corresponding array value will be false.

multiSet() public method

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.
Since: 2.0.7
public multiSet ( array $items, integer $duration, yii\caching\Dependency $dependency = null ) : array
$items array the items to be cached, as key-value pairs.
$duration integer default number of seconds in which the cached values will expire. 0 means never expire.
$dependency yii\caching\Dependency dependency of the cached items. If the dependency changes, the corresponding values in the cache will be invalidated when it is fetched via [[get()]]. This parameter is ignored if [[serializer]] is false.
return array array of failed keys

offsetExists() public method

This method is required by the interface [[\ArrayAccess]].
public offsetExists ( string $key ) : boolean
$key string a key identifying the cached value
return boolean

offsetGet() public method

This method is required by the interface [[\ArrayAccess]].
public offsetGet ( string $key ) : mixed
$key string a key identifying the cached value
return mixed the value stored in cache, false if the value is not in the cache or expired.

offsetSet() public method

If the cache already contains such a key, the existing value will be replaced with the new ones. To add expiration and dependencies, use the Cache::set method. This method is required by the interface [[\ArrayAccess]].
public offsetSet ( string $key, mixed $value )
$key string the key identifying the value to be cached
$value mixed the value to be cached

offsetUnset() public method

Deletes the value with the specified key from cache This method is required by the interface [[\ArrayAccess]].
public offsetUnset ( string $key )
$key string the key of the value to be deleted

set() public method

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.
public set ( mixed $key, mixed $value, integer $duration = null, yii\caching\Dependency $dependency = null ) : boolean
$key mixed a key identifying the value to be cached. This can be a simple string or a complex data structure consisting of factors representing the key.
$value mixed the value to be cached
$duration integer default duration in seconds before the cache will expire. If not set, default [[ttl]] value is used.
$dependency yii\caching\Dependency dependency of the cached item. If the dependency changes, the corresponding value in the cache will be invalidated when it is fetched via [[get()]]. This parameter is ignored if [[serializer]] is false.
return boolean whether the value is successfully stored into cache

setValue() abstract protected method

This method should be implemented by child classes to store the data in specific cache storage.
abstract protected setValue ( string $key, mixed $value, integer $duration ) : boolean
$key string the key identifying the value to be cached
$value mixed the value to be cached. Most often it's a string. If you have disabled [[serializer]], it could be something else.
$duration integer the number of seconds in which the cached value will expire. 0 means never expire.
return boolean true if the value is successfully stored into cache, false otherwise

setValues() protected method

The default implementation calls Cache::setValue multiple times store values one by one. If the underlying cache storage supports multi-set, this method should be overridden to exploit that feature.
protected setValues ( array $data, integer $duration ) : array
$data array array where key corresponds to cache key while value is the value stored
$duration integer the number of seconds in which the cached values will expire. 0 means never expire.
return array array of failed keys

Property Details

$defaultDuration public_oe property

default duration in seconds before a cache entry will expire. Default value is 0, meaning infinity. This value is used by Cache::set if the duration is not explicitly given.
Since: 2.0.11
public $defaultDuration

$keyPrefix public_oe property

a string prefixed to every cache key so that it is unique globally in the whole cache storage. It is recommended that you set a unique cache key prefix for each application if the same cache storage is being used by different applications. To ensure interoperability, only alphanumeric characters should be used.
public $keyPrefix

$serializer public_oe property

the functions used to serialize and unserialize cached data. Defaults to null, meaning using the default PHP serialize() and unserialize() functions. If you want to use some more efficient serializer (e.g. igbinary), you may configure this property with a two-element array. The first element specifies the serialization function, and the second the deserialization function. If this property is set false, data will be directly sent to and retrieved from the underlying cache component without any serialization or deserialization. You should not turn off serialization if you are using [[Dependency|cache dependency]], because it relies on data serialization. Also, some implementations of the cache can not correctly save and retrieve data different from a string type.
public $serializer