1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
namespace yii\caching;
use Yii;
use yii\base\Component;
use yii\base\InvalidConfigException;
use yii\helpers\StringHelper;
/**
* Cache is the base class for cache classes supporting different cache storage implementation.
*
* A data item can be stored in 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, $expire, $dependency);
* }
* ~~~
*
* Because Cache implements the ArrayAccess interface, it can be used like an array. For example,
*
* ~~~
* $cache['foo'] = 'some data';
* echo $cache['foo'];
* ~~~
*
* Derived classes should implement the following methods:
*
* - [[getValue()]]: retrieve the value with a key (if any) from cache
* - [[setValue()]]: store the value with a key into cache
* - [[addValue()]]: store the value only if the cache does not have this key before
* - [[deleteValue()]]: delete the value with the specified key from cache
* - [[flushValues()]]: delete all values from cache
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
abstract class Cache extends Component implements \ArrayAccess
{
/**
* @var string a string prefixed to every cache key so that it is unique. If not set,
* it will use a prefix generated from [[Application::id]]. You may set this property to be an empty string
* if you don't want to use key prefix. It is recommended that you explicitly set this property to some
* static value if the cached data needs to be shared among multiple applications.
*
* To ensure interoperability, only alphanumeric characters should be used.
*/
public $keyPrefix;
/**
* @var array|boolean the functions used to serialize and unserialize cached data. Defaults to null, meaning
* using the default PHP `serialize()` and `unserialize()` functions. If you want to use some more efficient
* serializer (e.g. [igbinary](http://pecl.php.net/package/igbinary)), you may configure this property with
* a two-element array. The first element specifies the serialization function, and the second the deserialization
* function. If this property is set false, data will be directly sent to and retrieved from the underlying
* cache component without any serialization or deserialization. You should not turn off serialization if
* you are using [[Dependency|cache dependency]], because it relies on data serialization.
*/
public $serializer;
/**
* Initializes the application component.
* This method overrides the parent implementation by setting default cache key prefix.
*/
public function init()
{
parent::init();
if ($this->keyPrefix === null) {
$this->keyPrefix = substr(md5(Yii::$app->id), 0, 5);
}
}
/**
* 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 [[keyPrefix]]. Otherwise, a normalized key
* is generated by serializing the given key, applying MD5 hashing, and prefixing with [[keyPrefix]].
*
* @param mixed $key the key to be normalized
* @return string the generated cache key
*/
protected function buildKey($key)
{
if (is_string($key)) {
$key = ctype_alnum($key) && StringHelper::byteLength($key) <= 32 ? $key : md5($key);
} else {
$key = md5(json_encode($key));
}
return $this->keyPrefix . $key;
}
/**
* Retrieves a value from cache with a specified key.
* @param mixed $key 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.
*/
public function get($key)
{
$key = $this->buildKey($key);
$value = $this->getValue($key);
if ($value === false || $this->serializer === false) {
return $value;
} elseif ($this->serializer === null) {
$value = unserialize($value);
} else {
$value = call_user_func($this->serializer[1], $value);
}
if (is_array($value) && !($value[1] instanceof Dependency && $value[1]->getHasChanged($this))) {
return $value[0];
} else {
return false;
}
}
/**
* 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.
* @param mixed $key 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)
{
$key = $this->buildKey($key);
$value = $this->getValue($key);
return $value !== false;
}
/**
* 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.
* @param array $keys list of 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.
*/
public function mget($keys)
{
$keyMap = [];
foreach ($keys as $key) {
$keyMap[$key] = $this->buildKey($key);
}
$values = $this->getValues(array_values($keyMap));
$results = [];
foreach ($keyMap as $key => $newKey) {
$results[$key] = false;
if (isset($values[$newKey])) {
if ($this->serializer === false) {
$results[$key] = $values[$newKey];
} else {
$value = $this->serializer === null ? unserialize($values[$newKey])
: call_user_func($this->serializer[1], $values[$newKey]);
if (is_array($value) && !($value[1] instanceof Dependency && $value[1]->getHasChanged($this))) {
$results[$key] = $value[0];
}
}
}
}
return $results;
}
/**
* 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.
*
* @param mixed $key 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.
* @param mixed $value the value to be cached
* @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
* @param Dependency $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 [[serializer]] is false.
* @return boolean whether the value is successfully stored into cache
*/
public function set($key, $value, $expire = 0, $dependency = null)
{
if ($dependency !== null && $this->serializer !== false) {
$dependency->evaluateDependency($this);
}
if ($this->serializer === null) {
$value = serialize([$value, $dependency]);
} elseif ($this->serializer !== false) {
$value = call_user_func($this->serializer[0], [$value, $dependency]);
}
$key = $this->buildKey($key);
return $this->setValue($key, $value, $expire);
}
/**
* 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.
*
* @param array $items the items to be cached, as key-value pairs.
* @param integer $expire default number of seconds in which the cached values will expire. 0 means never expire.
* @param Dependency $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 [[serializer]] is false.
* @return boolean whether the items are successfully stored into cache
*/
public function mset($items, $expire = 0, $dependency = null)
{
if ($dependency !== null && $this->serializer !== false) {
$dependency->evaluateDependency($this);
}
$data = [];
foreach ($items as $key => $value) {
$itemKey = $this->buildKey($key);
if ($this->serializer === null) {
$itemValue = serialize([$value, $dependency]);
} elseif ($this->serializer !== false) {
$itemValue = call_user_func($this->serializer[0], [$value, $dependency]);
}
$data[$itemKey] = $itemValue;
}
return $this->setValues($data, $expire);
}
/**
* 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.
*
* @param array $items the items to be cached, as key-value pairs.
* @param integer $expire default number of seconds in which the cached values will expire. 0 means never expire.
* @param Dependency $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 [[serializer]] is false.
* @return boolean whether the items are successfully stored into cache
*/
public function madd($items, $expire = 0, $dependency = null)
{
if ($dependency !== null && $this->serializer !== false) {
$dependency->evaluateDependency($this);
}
$data = [];
foreach ($items as $key => $value) {
$itemKey = $this->buildKey($key);
if ($this->serializer === null) {
$itemValue = serialize([$value, $dependency]);
} elseif ($this->serializer !== false) {
$itemValue = call_user_func($this->serializer[0], [$value, $dependency]);
}
$data[$itemKey] = $itemValue;
}
return $this->addValues($data, $expire);
}
/**
* 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.
* @param mixed $key 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.
* @param mixed $value the value to be cached
* @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
* @param Dependency $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 [[serializer]] is false.
* @return boolean whether the value is successfully stored into cache
*/
public function add($key, $value, $expire = 0, $dependency = null)
{
if ($dependency !== null && $this->serializer !== false) {
$dependency->evaluateDependency($this);
}
if ($this->serializer === null) {
$value = serialize([$value, $dependency]);
} elseif ($this->serializer !== false) {
$value = call_user_func($this->serializer[0], [$value, $dependency]);
}
$key = $this->buildKey($key);
return $this->addValue($key, $value, $expire);
}
/**
* Deletes a value with the specified key from cache
* @param mixed $key 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
*/
public function delete($key)
{
$key = $this->buildKey($key);
return $this->deleteValue($key);
}
/**
* Deletes all values from cache.
* Be careful of performing this operation if the cache is shared among multiple applications.
* @return boolean whether the flush operation was successful.
*/
public function flush()
{
return $this->flushValues();
}
/**
* Retrieves a value from cache with a specified key.
* This method should be implemented by child classes to retrieve the data
* from specific cache storage.
* @param string $key a unique key identifying the cached value
* @return string|boolean the value stored in cache, false if the value is not in the cache or expired.
*/
abstract protected function getValue($key);
/**
* Stores a value identified by a key in cache.
* This method should be implemented by child classes to store the data
* in specific cache storage.
* @param string $key the key identifying the value to be cached
* @param string $value the value to be cached
* @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
* @return boolean true if the value is successfully stored into cache, false otherwise
*/
abstract protected function setValue($key, $value, $expire);
/**
* Stores a value identified by a key into cache if the cache does not contain this key.
* This method should be implemented by child classes to store the data
* in specific cache storage.
* @param string $key the key identifying the value to be cached
* @param string $value the value to be cached
* @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
* @return boolean true if the value is successfully stored into cache, false otherwise
*/
abstract protected function addValue($key, $value, $expire);
/**
* Deletes a value with the specified key from cache
* This method should be implemented by child classes to delete the data from actual cache storage.
* @param string $key the key of the value to be deleted
* @return boolean if no error happens during deletion
*/
abstract protected function deleteValue($key);
/**
* Deletes all values from cache.
* Child classes may implement this method to realize the flush operation.
* @return boolean whether the flush operation was successful.
*/
abstract protected function flushValues();
/**
* Retrieves multiple values from cache with the specified keys.
* The default implementation calls [[getValue()]] multiple times to retrieve
* the cached values one by one. If the underlying cache storage supports multiget,
* this method should be overridden to exploit that feature.
* @param array $keys a list of keys identifying the cached values
* @return array a list of cached values indexed by the keys
*/
protected function getValues($keys)
{
$results = [];
foreach ($keys as $key) {
$results[$key] = $this->getValue($key);
}
return $results;
}
/**
* Stores multiple key-value pairs in cache.
* The default implementation calls [[setValue()]] multiple times store values one by one. If the underlying cache
* storage supports multiset, this method should be overridden to exploit that feature.
* @param array $data array where key corresponds to cache key while value is the value stored
* @param integer $expire the number of seconds in which the cached values will expire. 0 means never expire.
* @return array array of failed keys
*/
protected function setValues($data, $expire)
{
$failedKeys = [];
foreach ($data as $key => $value)
{
if ($this->setValue($key, $value, $expire) === false) {
$failedKeys[] = $key;
}
}
return $failedKeys;
}
/**
* Adds multiple key-value pairs to cache.
* The default implementation calls [[addValue()]] multiple times add values one by one. If the underlying cache
* storage supports multiadd, this method should be overridden to exploit that feature.
* @param array $data array where key corresponds to cache key while value is the value stored
* @param integer $expire the number of seconds in which the cached values will expire. 0 means never expire.
* @return array array of failed keys
*/
protected function addValues($data, $expire)
{
$failedKeys = [];
foreach ($data as $key => $value)
{
if ($this->addValue($key, $value, $expire) === false) {
$failedKeys[] = $key;
}
}
return $failedKeys;
}
/**
* Returns whether there is a cache entry with a specified key.
* This method is required by the interface ArrayAccess.
* @param string $key a key identifying the cached value
* @return boolean
*/
public function offsetExists($key)
{
return $this->get($key) !== false;
}
/**
* Retrieves the value from cache with a specified key.
* This method is required by the interface ArrayAccess.
* @param string $key a key identifying the cached value
* @return mixed the value stored in cache, false if the value is not in the cache or expired.
*/
public function offsetGet($key)
{
return $this->get($key);
}
/**
* Stores the value identified by a key into cache.
* If the cache already contains such a key, the existing value will be
* replaced with the new ones. To add expiration and dependencies, use the [[set()]] method.
* This method is required by the interface ArrayAccess.
* @param string $key the key identifying the value to be cached
* @param mixed $value the value to be cached
*/
public function offsetSet($key, $value)
{
$this->set($key, $value);
}
/**
* Deletes the value with the specified key from cache
* This method is required by the interface ArrayAccess.
* @param string $key the key of the value to be deleted
*/
public function offsetUnset($key)
{
$this->delete($key);
}
}