Class yii\redis\Cache

Inheritanceyii\redis\Cache » yii\caching\Cache
Available since extension's version2.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

Hide inherited 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

Hide inherited 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

Hide inherited 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

Hide inherited properties

$enableReplicas public property (available since version 2.0.8)

Whether to enable read / get from redis replicas.

public boolean $enableReplicas false
$forceClusterMode public property (available since version 2.0.11)

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.

$isCluster public property

Whether redis is running in cluster mode or not.

public boolean $isCluster null
$redis public property

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.

$replicas public property (available since version 2.0.8)

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'],
],
public array $replicas = []
$shareDatabase public property (available since version 2.0.12)

Whether redis database is shared and can contain other data than cache. Setting this to true will change flush() behavior - instead of using FLUSHDB command, component will iterate through all keys in database and remove only these with matching $keyPrefix. Note that this will no longer be an atomic operation and it is much less efficient than FLUSHDB command. It is recommended to use separate database for cache and leave this value as false.

public boolean $shareDatabase false

Method Details

Hide inherited methods

addValue() protected method

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']);
}

            
buildKey() public method

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);
}

            
deleteValue() protected method

protected void deleteValue ( $key )
$key

                protected function deleteValue($key)
{
    return (bool) $this->redis->executeCommand('DEL', [$key]);
}

            
exists() public 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. 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)]);
}

            
flushValues() protected method

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');
}

            
getIsCluster() public method (available since version 2.0.11)

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;
}

            
getReplica() protected method (available since version 2.0.8)

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;
}

            
getValue() protected method

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;
}

            
getValues() protected method

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;
}

            
init() public method

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());
}

            
setValue() protected method

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]);
}

            
setValues() protected method

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;
}