Interface yii\caching\CacheInterface

All Classes | Methods

Extends	ArrayAccess
Implemented by	yii\caching\ApcCache, yii\caching\ArrayCache, yii\caching\Cache, yii\caching\DbCache, yii\caching\DummyCache, yii\caching\FileCache, yii\caching\MemCache, yii\caching\WinCache, yii\caching\XCache, yii\caching\ZendDataCache, yii\mongodb\Cache, yii\redis\Cache
Available since version	2.0.13.
Source Code	https://github.com/yiisoft/yii2/blob/master/framework/caching/CacheInterface.php

CacheInterface is the base interface for cache.

A data item can be stored in the cache by calling set() and be retrieved back later (in the same or different request) by get(). In both operations, a key identifying the data item is required. An expiration time and/or a dependency can also be specified when calling set(). If the data item expires or the dependency changes at the time of calling get(), the cache will return no data.

A typical usage pattern of cache is like the following:

$key = 'demo';
$data = $cache->get($key);
if ($data === false) {
    // ...generate $data here...
    $cache->set($key, $data, $duration, $dependency);
}

Because CacheInterface extends the ArrayAccess interface, it can be used like an array. For example,

$cache['foo'] = 'some data';
echo $cache['foo'];

For more details and usage information on Cache, see the guide article on caching.

Public Methods

Hide inherited methods

Method	Description	Defined By
add()	Stores a value identified by a key into cache if the cache does not contain this key.	yii\caching\CacheInterface
buildKey()	Builds a normalized cache key from a given key.	yii\caching\CacheInterface
delete()	Deletes a value with the specified key from cache.	yii\caching\CacheInterface
exists()	Checks whether a specified key exists in the cache.	yii\caching\CacheInterface
flush()	Deletes all values from cache.	yii\caching\CacheInterface
get()	Retrieves a value from cache with a specified key.	yii\caching\CacheInterface
getOrSet()	Method combines both set() and get() methods to retrieve value identified by a $key, or to store the result of $callable execution if there is no cache available for the $key.	yii\caching\CacheInterface
multiAdd()	Stores multiple items in cache. Each item contains a value identified by a key.	yii\caching\CacheInterface
multiGet()	Retrieves multiple values from cache with the specified keys.	yii\caching\CacheInterface
multiSet()	Stores multiple items in cache. Each item contains a value identified by a key.	yii\caching\CacheInterface
set()	Stores a value identified by a key into cache.	yii\caching\CacheInterface

Method Details

add() public abstract method

Stores a value identified by a key into cache if the cache does not contain this key.

Nothing will be done if the cache already contains the key.

public abstract boolean add ( $key, $value, $duration = 0, $dependency = null )
$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 \yii\caching\serializer is false.
return	boolean	Whether the value is successfully stored into cache

buildKey() public abstract method

Builds a normalized cache key from a given key.

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 \yii\caching\keyPrefix. Otherwise, a normalized key is generated by serializing the given key, applying MD5 hashing, and prefixing with \yii\caching\keyPrefix.

public abstract string buildKey ( $key )
$key	mixed	The key to be normalized
return	string	The generated cache key

delete() public abstract method

Deletes a value with the specified key from cache.

public abstract boolean delete ( $key )
$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

exists() public abstract method

Checks whether a specified key exists in the cache.

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 abstract boolean exists ( $key )
$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 abstract method

Deletes all values from cache.

Be careful of performing this operation if the cache is shared among multiple applications.

public abstract boolean flush ( )
return	boolean	Whether the flush operation was successful.

get() public abstract method

Retrieves a value from cache with a specified key.

public abstract mixed get ( $key )
$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.

getOrSet() public abstract method

Method combines both set() and get() methods to retrieve value identified by a $key, or to store the result of $callable execution if there is no cache available for the $key.

Usage example:

public function getTopProducts($count = 10) {
    $cache = $this->cache; // Could be Yii::$app->cache
    return $cache->getOrSet(['top-n-products', 'n' => $count], function ($cache) use ($count) {
        return Products::find()->mostPopular()->limit($count)->all();
    }, 1000);
}

public abstract mixed getOrSet ( $key, $callable, $duration = null, $dependency = null )
$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.
$callable	callable\|Closure	The callable or closure that will be used to generate a value to be cached. In case $callable returns `false`, the value will not be cached.
$duration	integer	Default duration in seconds before the cache will expire. If not set, \yii\caching\defaultDuration value will be 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 \yii\caching\serializer is `false`.
return	mixed	Result of $callable execution

multiAdd() public abstract method

Stores multiple items in cache. Each item contains a value identified by a key.

If the cache already contains such a key, the existing value and expiration time will be preserved.

public abstract array multiAdd ( $items, $duration = 0, $dependency = null )
$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 \yii\caching\serializer is false.
return	array	Array of failed keys

multiGet() public abstract method

Retrieves multiple values from cache with the specified keys.

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.

public abstract array multiGet ( $keys )
$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 abstract method

Stores multiple items in cache. Each item contains a value identified by a key.

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.

public abstract array multiSet ( $items, $duration = 0, $dependency = null )
$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 \yii\caching\serializer is false.
return	array	Array of failed keys

set() public abstract method

Stores a value identified by a key into cache.

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.

public abstract boolean set ( $key, $value, $duration = null, $dependency = null )
$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 \yii\caching\defaultDuration 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 \yii\caching\serializer is false.
return	boolean	Whether the value is successfully stored into cache