Class yii\redis\Cache
Inheritance | yii\redis\Cache » yii\caching\Cache |
---|---|
Available since extension's version | 2.0 |
Source Code | https://github.com/yiisoft/yii2-redis/blob/master/src/Cache.php |
Redis Cache implements a cache application component based on redis key-value store.
Redis Cache requires redis version 2.6.12 or higher to work properly.
It needs to be configured with a redis yii\redis\Connection. By default it will use the redis
application component.
Note: It is recommended to use separate database for cache and do not share it with other components. If you need to share database, you should set $shareDatabase to
true
and make sure that $keyPrefix has unique value which will allow to distinguish between cache keys and other data in database.
See yii\caching\Cache manual for common cache operations that redis Cache supports.
Unlike the yii\caching\Cache, redis Cache allows the expire parameter of set, add, mset and madd to be a floating point number, so you may specify the time in milliseconds (e.g. 0.1 will be 100 milliseconds).
To use redis Cache as the cache application component, configure the application as follows,
[
'components' => [
'cache' => [
'class' => 'yii\redis\Cache',
'redis' => [
'hostname' => 'localhost',
'port' => 6379,
'database' => 0,
]
],
],
]
Or if you have configured the redis yii\redis\Connection as an application component, the following is sufficient:
[
'components' => [
'cache' => [
'class' => 'yii\redis\Cache',
// 'redis' => 'redis' // id of the connection application component
],
],
]
If you have multiple redis replicas (e.g. AWS ElasticCache Redis) you can configure the cache to send read operations to the replicas. If no replicas are configured, all operations will be performed on the master connection configured via the $redis property.
[
'components' => [
'cache' => [
'class' => 'yii\redis\Cache',
'enableReplicas' => true,
'replicas' => [
// config for replica redis connections, (default class will be yii\redis\Connection if not provided)
// you can optionally put in master as hostname as well, as all GET operation will use replicas
'redis',//id of Redis [[Connection]] Component
['hostname' => 'redis-slave-002.xyz.0001.apse1.cache.amazonaws.com'],
['hostname' => 'redis-slave-003.xyz.0001.apse1.cache.amazonaws.com'],
],
],
],
]
If you're using redis in cluster mode and want to use MGET
and MSET
effectively, you will need to supply a
hash tag to allocate cache keys to the same hash slot.
\Yii::$app->cache->multiSet([
'posts{user1}' => 123,
'settings{user1}' => [
'showNickname' => false,
'sortBy' => 'created_at',
],
'unreadMessages{user1}' => 5,
]);
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$enableReplicas | boolean | Whether to enable read / get from redis replicas. | yii\redis\Cache |
$forceClusterMode | boolean|null | Force cluster mode, don't check on every request. | yii\redis\Cache |
$isCluster | boolean | Whether redis is running in cluster mode or not. | yii\redis\Cache |
$redis | yii\redis\Connection|string|array | The Redis yii\redis\Connection object or the application component ID of the Redis yii\redis\Connection. | yii\redis\Cache |
$replicas | array | The Redis yii\redis\Connection configurations for redis replicas. | yii\redis\Cache |
$shareDatabase | boolean | Whether redis database is shared and can contain other data than cache. | yii\redis\Cache |
Public Methods
Method | Description | Defined By |
---|---|---|
buildKey() | yii\redis\Cache | |
exists() | Checks whether a specified key exists in the cache. | yii\redis\Cache |
getIsCluster() | Returns true if the redis extension is forced to run in cluster mode through config or the redis command
CLUSTER INFO executes successfully, false otherwise. |
yii\redis\Cache |
init() | Initializes the redis Cache component. | yii\redis\Cache |
Protected Methods
Method | Description | Defined By |
---|---|---|
addValue() | yii\redis\Cache | |
deleteValue() | yii\redis\Cache | |
flushValues() | yii\redis\Cache | |
getReplica() | It will return the current Replica Redis yii\redis\Connection, and fall back to default $redis yii\redis\Connection defined in this instance. Only used in getValue() and getValues(). | yii\redis\Cache |
getValue() | yii\redis\Cache | |
getValues() | yii\redis\Cache | |
setValue() | yii\redis\Cache | |
setValues() | yii\redis\Cache |
Property Details
Whether to enable read / get from redis replicas.
Force cluster mode, don't check on every request. If this is null, cluster mode will be checked once per request whenever the cache is accessed. To disable the check, set to true if cluster mode should be enabled, or false if it should be disabled.
Whether redis is running in cluster mode or not.
The Redis yii\redis\Connection object or the application component ID of the Redis yii\redis\Connection. This can also be an array that is used to create a redis yii\redis\Connection instance in case you do not want do configure redis connection as an application component. After the Cache object is created, if you want to change this property, you should only assign it with a Redis yii\redis\Connection object.
The Redis yii\redis\Connection configurations for redis replicas. Each entry is a class configuration, which will be used to instantiate a replica connection. The default class is yii\redis\Connection. You should at least provide a hostname.
Configuration example:
'replicas' => [
'redis',
['hostname' => 'redis-slave-002.xyz.0001.apse1.cache.amazonaws.com'],
['hostname' => 'redis-slave-003.xyz.0001.apse1.cache.amazonaws.com'],
],
Method Details
protected void addValue ( $key, $value, $expire ) | ||
$key | ||
$value | ||
$expire |
protected function addValue($key, $value, $expire)
{
if ($expire == 0) {
return (bool) $this->redis->executeCommand('SET', [$key, $value, 'NX']);
}
$expire = (int) ($expire * 1000);
return (bool) $this->redis->executeCommand('SET', [$key, $value, 'PX', $expire, 'NX']);
}
public void buildKey ( $key ) | ||
$key |
public function buildKey($key)
{
if (
is_string($key)
&& $this->isCluster
&& preg_match('/^(.*)({.+})(.*)$/', $key, $matches) === 1) {
$this->_hashTagAvailable = true;
return parent::buildKey($matches[1] . $matches[3]) . $matches[2];
}
return parent::buildKey($key);
}
protected void deleteValue ( $key ) | ||
$key |
protected function deleteValue($key)
{
return (bool) $this->redis->executeCommand('DEL', [$key]);
}
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. 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 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. |
---|
public function exists($key)
{
return (bool) $this->redis->executeCommand('EXISTS', [$this->buildKey($key)]);
}
protected void flushValues ( ) |
protected function flushValues()
{
if ($this->shareDatabase) {
$cursor = 0;
do {
list($cursor, $keys) = $this->redis->scan($cursor, 'MATCH', $this->keyPrefix . '*');
$cursor = (int) $cursor;
if (!empty($keys)) {
$this->redis->executeCommand('DEL', $keys);
}
} while ($cursor !== 0);
return true;
}
return $this->redis->executeCommand('FLUSHDB');
}
Returns true
if the redis extension is forced to run in cluster mode through config or the redis command
CLUSTER INFO
executes successfully, false
otherwise.
Setting $forceClusterMode to either true
or false
is preferred.
public boolean getIsCluster ( ) | ||
return | boolean |
Whether redis is running in cluster mode or not |
---|
public function getIsCluster()
{
if ($this->forceClusterMode !== null) {
return $this->forceClusterMode;
}
if ($this->_isCluster === null) {
$this->_isCluster = false;
try {
$this->redis->executeCommand('CLUSTER INFO');
$this->_isCluster = true;
} catch (Exception $exception) {
// if redis is running without cluster support, this command results in:
// `ERR This instance has cluster support disabled`
// and [[Connection::executeCommand]] throws an exception
// we want to ignore it
}
}
return $this->_isCluster;
}
It will return the current Replica Redis yii\redis\Connection, and fall back to default $redis yii\redis\Connection defined in this instance. Only used in getValue() and getValues().
protected array|string|yii\redis\Connection getReplica ( ) | ||
throws | \yii\base\InvalidConfigException |
---|
protected function getReplica()
{
if ($this->enableReplicas === false) {
return $this->redis;
}
if ($this->_replica !== null) {
return $this->_replica;
}
if (empty($this->replicas)) {
return $this->_replica = $this->redis;
}
$replicas = $this->replicas;
shuffle($replicas);
$config = array_shift($replicas);
$this->_replica = Instance::ensure($config, Connection::className());
return $this->_replica;
}
protected void getValue ( $key ) | ||
$key |
protected function getValue($key)
{
$value = $this->getReplica()->executeCommand('GET', [$key]);
if ($value === null) {
return false; // Key is not in the cache or expired
}
return $value;
}
protected void getValues ( $keys ) | ||
$keys |
protected function getValues($keys)
{
if ($this->isCluster && !$this->_hashTagAvailable) {
return parent::getValues($keys);
}
$response = $this->getReplica()->executeCommand('MGET', $keys);
$result = [];
$i = 0;
foreach ($keys as $key) {
$result[$key] = $response[$i++];
}
$this->_hashTagAvailable = false;
return $result;
}
Initializes the redis Cache component.
This method will initialize the $redis property to make sure it refers to a valid redis connection.
public void init ( ) | ||
throws | \yii\base\InvalidConfigException |
if $redis is invalid. |
---|
public function init()
{
parent::init();
$this->redis = Instance::ensure($this->redis, Connection::className());
}
protected void setValue ( $key, $value, $expire ) | ||
$key | ||
$value | ||
$expire |
protected function setValue($key, $value, $expire)
{
if ($expire == 0) {
return (bool) $this->redis->executeCommand('SET', [$key, $value]);
}
$expire = (int) ($expire * 1000);
return (bool) $this->redis->executeCommand('SET', [$key, $value, 'PX', $expire]);
}
protected void setValues ( $data, $expire ) | ||
$data | ||
$expire |
protected function setValues($data, $expire)
{
if ($this->isCluster && !$this->_hashTagAvailable) {
return parent::setValues($data, $expire);
}
$args = [];
foreach ($data as $key => $value) {
$args[] = $key;
$args[] = $value;
}
$failedKeys = [];
if ($expire == 0) {
$this->redis->executeCommand('MSET', $args);
} else {
$expire = (int) ($expire * 1000);
$this->redis->executeCommand('MULTI');
$this->redis->executeCommand('MSET', $args);
$index = [];
foreach ($data as $key => $value) {
$this->redis->executeCommand('PEXPIRE', [$key, $expire]);
$index[] = $key;
}
$result = $this->redis->executeCommand('EXEC');
array_shift($result);
foreach ($result as $i => $r) {
if ($r != 1) {
$failedKeys[] = $index[$i];
}
}
}
$this->_hashTagAvailable = false;
return $failedKeys;
}