README.md 5.29 KB
Newer Older
Carsten Brandt committed
1 2
Redis Cache, Session and ActiveRecord for Yii 2
===============================================
3 4

This extension provides the [redis](http://redis.io/) key-value store support for the Yii2 framework.
munawer committed
5
It includes a `Cache` and `Session` storage handler and implements the `ActiveRecord` pattern that allows
Carsten Brandt committed
6
you to store active records in redis.
7 8 9 10 11

To use this extension, you have to configure the Connection class in your application configuration:

```php
return [
12 13
    //....
    'components' => [
14 15 16 17 18 19
        'redis' => [
            'class' => 'yii\redis\Connection',
            'hostname' => 'localhost',
            'port' => 6379,
            'database' => 0,
        ],
20
    ]
21 22 23
];
```

24 25 26 27 28
Requirements
------------

At least redis version 2.6.12 is required for all components to work properly.

Carsten Brandt committed
29 30 31 32 33 34 35 36
Installation
------------

The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

Either run

```
37
php composer.phar require --prefer-dist yiisoft/yii2-redis "*"
Carsten Brandt committed
38 39 40 41 42 43 44 45 46 47 48 49 50 51
```

or add

```json
"yiisoft/yii2-redis": "*"
```

to the require section of your composer.json.


Using the Cache component
-------------------------

52
To use the `Cache` component, in addition to configuring the connection as described above,
Carsten Brandt committed
53
you also have to configure the `cache` component to be `yii\redis\Cache`:
54 55 56

```php
return [
57 58 59 60 61 62 63
    //....
    'components' => [
        // ...
        'cache' => [
            'class' => 'yii\redis\Cache',
        ],
    ]
64 65 66
];
```

67
If you only use the redis cache, you can also configure the parameters of the connection within the
Carsten Brandt committed
68
cache component (no connection application component needs to be configured in this case):
69

70 71
```php
return [
72 73 74 75 76 77 78 79 80 81 82 83
    //....
    'components' => [
        // ...
        'cache' => [
            'class' => 'yii\redis\Cache',
            'redis' => [
                'hostname' => 'localhost',
                'port' => 6379,
                'database' => 0,
            ],
        ],
    ]
84 85
];
```
86

Carsten Brandt committed
87 88
Using the Session component
---------------------------
89

munawer committed
90
To use the `Session` component, in addition to configuring the connection as described above,
Carsten Brandt committed
91
you also have to configure the `session` component to be `yii\redis\Session`:
92

Carsten Brandt committed
93 94
```php
return [
95 96 97 98 99 100 101
    //....
    'components' => [
        // ...
        'session' => [
            'class' => 'yii\redis\Session',
        ],
    ]
Carsten Brandt committed
102
];
103 104
```

Carsten Brandt committed
105 106
If you only use the redis session, you can also configure the parameters of the connection within the
cache component (no connection application component needs to be configured in this case):
107

Carsten Brandt committed
108 109
```php
return [
110 111 112 113 114 115 116 117 118 119 120 121
    //....
    'components' => [
        // ...
        'session' => [
            'class' => 'yii\redis\Session',
            'redis' => [
                'hostname' => 'localhost',
                'port' => 6379,
                'database' => 0,
            ],
        ],
    ]
Carsten Brandt committed
122
];
123 124 125 126 127 128 129 130
```


Using the redis ActiveRecord
----------------------------

For general information on how to use yii's ActiveRecord please refer to the [guide](https://github.com/yiisoft/yii2/blob/master/docs/guide/active-record.md).

131
For defining a redis ActiveRecord class your record class needs to extend from [[yii\redis\ActiveRecord]] and
132
implement at least the `attributes()` method to define the attributes of the record.
133
A primary key can be defined via [[yii\redis\ActiveRecord::primaryKey()]] which defaults to `id` if not specified.
134 135 136 137 138 139 140 141
The primaryKey needs to be part of the attributes so make sure you have an `id` attribute defined if you do
not specify your own primary key.

The following is an example model called `Customer`:

```php
class Customer extends \yii\redis\ActiveRecord
{
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
    /**
     * @return array the list of attributes for this record
     */
    public function attributes()
    {
        return ['id', 'name', 'address', 'registration_date'];
    }

    /**
     * @return ActiveQuery defines a relation to the Order record (can be in other database, e.g. elasticsearch or sql)
     */
    public function getOrders()
    {
        return $this->hasMany(Order::className(), ['customer_id' => 'id']);
    }

    /**
     * Defines a scope that modifies the `$query` to return only active(status = 1) customers
     */
    public static function active($query)
    {
        $query->andWhere(['status' => 1]);
    }
165 166 167 168 169 170 171 172 173 174 175 176
}
```

The general usage of redis ActiveRecord is very similar to the database ActiveRecord as described in the
[guide](https://github.com/yiisoft/yii2/blob/master/docs/guide/active-record.md).
It supports the same interface and features except the following limitations:

- As redis does not support SQL the query API is limited to the following methods:
  `where()`, `limit()`, `offset()`, `orderBy()` and `indexBy()`.
  (orderBy() is not yet implemented: [#1305](https://github.com/yiisoft/yii2/issues/1305))
- `via`-relations can not be defined via a table as there are not tables in redis. You can only define relations via other records.

Carsten Brandt committed
177 178 179 180 181 182 183 184 185 186 187 188
It is also possible to define relations from redis ActiveRecords to normal ActiveRecord classes and vice versa.

Usage example:

```php
$customer = new Customer();
$customer->attributes = ['name' => 'test'];
$customer->save();
echo $customer->id; // id will automatically be incremented if not set explicitly

$customer = Customer::find()->where(['name' => 'test'])->one(); // find by query
$customer = Customer::find()->active()->all(); // find all by query (using the `active` scope)
189
```