* Cache is the base class for cache classes with different cache storage implementation.
* Cache is the base class for cache classes supporting different cache storage implementation.
*
* A data item can be stored in cache by calling {@link set} and be retrieved back
* later by {@link get}. In both operations, a key identifying the data item is required.
* An expiration time and/or a dependency can also be specified when calling {@link set}.
* If the data item expires or the dependency changes, calling {@link get} will not
* return back the data item.
* 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 [[CacheDependency|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.
*
* Note, by definition, cache does not ensure the existence of a value
* even if it does not expire. Cache is not meant to be a persistent storage.
* Derived classes should implement the following methods:
*
* Cache implements the interface {@link ICache} with the following methods:
* <ul>
* <li>{@link get} : retrieve the value with a key (if any) from cache</li>
* <li>{@link set} : store the value with a key into cache</li>
* <li>{@link add} : store the value only if cache does not have this key</li>
* <li>{@link delete} : delete the value with the specified key from cache</li>
* <li>{@link flush} : delete all values from cache</li>
* </ul>
* - [[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
*
* Child classes must implement the following methods:
* <ul>
* <li>{@link getValue}</li>
* <li>{@link setValue}</li>
* <li>{@link addValue}</li>
* <li>{@link deleteValue}</li>
* <li>{@link flushValues} (optional)</li>
* <li>{@link serializeValue} (optional)</li>
* <li>{@link unserializeValue} (optional)</li>
* </ul>
* Because Cache implements the ArrayAccess interface, it can be used like an array. For example,
*
* Cache also implements ArrayAccess so that it can be used like an array.
* ~~~
* $cache['foo'] = 'some data';
* echo $cache['foo'];
* ~~~
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
@ -52,18 +41,16 @@ use yii\base\Exception;
abstract class Cache extends ApplicationComponent implements \ArrayAccess
{
/**
* @var string a string prefixed to every cache key so that it is unique. Defaults to null which means
* to use the {@link CApplication::getId() application ID}. If different applications need to access the same
* pool of cached data, the same prefix should be set for each of the applications explicitly.
* @var string a string prefixed to every cache key so that it is unique. Defaults to null, meaning using
* the value of [[Application::id]] as the key prefix. 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.
*/
public $keyPrefix;
/**
* @var boolean whether to hash the cache key for normalization purpose. Defaults to true.
* Setting this property to false makes sure the cache
* key will not be tampered when calling the relevant methods {@link get()}, {@link set()}, {@link add()} and {@link delete()}. This is useful if a Yii
* application as well as an external application need to access the same cache pool (also see description of {@link keyPrefix} regarding this use case).
* However, without normalization you should make sure the affected cache backend does support the structure (charset, length, etc.) of all the provided
* cache keys, otherwise there might be unexpected behavior.
* @var boolean whether to hash the cache keys so that they can fit in the underlying cache storage.
* Defaults to true. If you set this to be false, you have to make sure the cache keys are allowed by
Qiang Xue
13 years ago