CacheInterface
extends
ArrayAccess
in
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|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.
Tags
Table of Contents
Methods
- add() : bool
- Stores a value identified by a key into cache if the cache does not contain this key.
- buildKey() : string
- Builds a normalized cache key from a given key.
- delete() : bool
- Deletes a value with the specified key from cache.
- exists() : bool
- Checks whether a specified key exists in the cache.
- flush() : bool
- Deletes all values from cache.
- get() : mixed
- Retrieves a value from cache with a specified key.
- getOrSet() : mixed
- 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.
- multiAdd() : array<string|int, mixed>
- Stores multiple items in cache. Each item contains a value identified by a key.
- multiGet() : array<string|int, mixed>
- Retrieves multiple values from cache with the specified keys.
- multiSet() : array<string|int, mixed>
- Stores multiple items in cache. Each item contains a value identified by a key.
- set() : bool
- Stores a value identified by a key into cache.
Methods
add()
Stores a value identified by a key into cache if the cache does not contain this key.
public
add(mixed $key, mixed $value[, int $duration = 0 ][, Dependency|null $dependency = null ]) : bool
Nothing will be done if the cache already contains the key.
Parameters
- $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 : int = 0
-
the number of seconds in which the cached value will expire. 0 means never expire.
- $dependency : Dependency|null = null
-
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 values
bool —whether the value is successfully stored into cache
buildKey()
Builds a normalized cache key from a given key.
public
buildKey(mixed $key) : string
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]].
Parameters
- $key : mixed
-
the key to be normalized
Return values
string —the generated cache key
delete()
Deletes a value with the specified key from cache.
public
delete(mixed $key) : bool
Parameters
- $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 values
bool —if no error happens during deletion
exists()
Checks whether a specified key exists in the cache.
public
exists(mixed $key) : bool
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.
Parameters
- $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 values
bool —true if a value exists in cache, false if the value is not in the cache or expired.
flush()
Deletes all values from cache.
public
flush() : bool
Be careful of performing this operation if the cache is shared among multiple applications.
Return values
bool —whether the flush operation was successful.
get()
Retrieves a value from cache with a specified key.
public
get(mixed $key) : mixed
Parameters
- $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 values
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()
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.
public
getOrSet(mixed $key, callable|Closure $callable[, int|null $duration = null ][, Dependency|null $dependency = null ]) : mixed
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);
}
Parameters
- $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 : int|null = null
-
default duration in seconds before the cache will expire. If not set, [[defaultDuration]] value will be used.
- $dependency : Dependency|null = null
-
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 values
mixed —result of $callable execution
multiAdd()
Stores multiple items in cache. Each item contains a value identified by a key.
public
multiAdd(array<string|int, mixed> $items[, int $duration = 0 ][, Dependency|null $dependency = null ]) : array<string|int, mixed>
If the cache already contains such a key, the existing value and expiration time will be preserved.
Parameters
- $items : array<string|int, mixed>
-
the items to be cached, as key-value pairs.
- $duration : int = 0
-
default number of seconds in which the cached values will expire. 0 means never expire.
- $dependency : Dependency|null = null
-
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 values
array<string|int, mixed> —array of failed keys
multiGet()
Retrieves multiple values from cache with the specified keys.
public
multiGet(array<string|int, string> $keys) : array<string|int, mixed>
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.
Parameters
- $keys : array<string|int, string>
-
list of string keys identifying the cached values
Return values
array<string|int, mixed> —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()
Stores multiple items in cache. Each item contains a value identified by a key.
public
multiSet(array<string|int, mixed> $items[, int|null $duration = null ][, Dependency|null $dependency = null ]) : array<string|int, mixed>
If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.
Parameters
- $items : array<string|int, mixed>
-
the items to be cached, as key-value pairs.
- $duration : int|null = null
-
default duration in seconds before the cache will expire. If not set, default [[defaultDuration]] value is used.
- $dependency : Dependency|null = null
-
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 values
array<string|int, mixed> —array of failed keys
set()
Stores a value identified by a key into cache.
public
set(mixed $key, mixed $value[, int|null $duration = null ][, Dependency|null $dependency = null ]) : bool
If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.
Parameters
- $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 : int|null = null
-
default duration in seconds before the cache will expire. If not set, default [[defaultDuration]] value is used.
- $dependency : Dependency|null = null
-
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 values
bool —whether the value is successfully stored into cache