This library is a wrapper around PSR-16 compatible caching libraries providing own features. It is used in Yii Framework but is usable separately.
- Built on top of PSR-16, it can use any PSR-16 cache as a handler.
- Ability to set default TTL and key prefix per cache instance.
- Provides a built-in behavior to cache stampede prevention.
- Adds cache invalidation dependencies on top of PSR-16.
- PHP 7.4 or higher.
JSON
PHP extension.Mbstring
PHP extension.
The package could be installed with composer:
composer require yiisoft/cache --prefer-dist
There are two ways to get cache instance. If you need PSR-16 instance, you can simply create it:
$arrayCache = new \Yiisoft\Cache\ArrayCache();
In order to set a global key prefix:
$arrayCacheWithPrefix = new \Yiisoft\Cache\PrefixedCache(new \Yiisoft\Cache\ArrayCache(), 'myapp_');
If you need a simpler yet more powerful way to cache values based on recomputation callbacks use getOrSet()
and remove()
, additional features such as invalidation dependencies and "Probably early expiration"
stampede prevention, you should wrap PSR-16 cache instance with \Yiisoft\Cache\Cache
:
$cache = new \Yiisoft\Cache\Cache($arrayCache);
Set a default TTL:
$cache = new \Yiisoft\Cache\Cache($arrayCache, 60 * 60); // 1 hour
Typical PSR-16 cache usage is the following:
$cache = new \Yiisoft\Cache\ArrayCache();
$parameters = ['user_id' => 42];
$key = 'demo';
// Try retrieving $data from cache.
$data = $cache->get($key);
if ($data === null) {
// $data is not found in cache, calculate it from scratch.
$data = calculateData($parameters);
// Store $data in cache for an hour so that it can be retrieved next time.
$cache->set($key, $data, 3600);
}
// $data is available here.
In order to delete value you can use:
$cache->delete($key);
// Or all cache
$cache->clear();
To work with values in a more efficient manner, batch operations should be used:
getMultiple()
setMultiple()
deleteMultiple()
When using extended cache i.e. PSR-16 cache wrapped with \Yiisoft\Cache\Cache
, you can use alternative syntax that
is less repetitive:
$cache = new \Yiisoft\Cache\Cache(new \Yiisoft\Cache\ArrayCache());
$key = ['top-products', $count = 10];
$data = $cache->getOrSet($key, function (\Psr\SimpleCache\CacheInterface $cache) use ($count) {
return getTopProductsFromDatabase($count);
}, 3600);
Normalization of the key occurs using the Yiisoft\Cache\CacheKeyNormalizer
.
In order to delete value you can use:
$cache->remove($key);
You can use PSR-16 methods the following way, but remember that getting and setting the cache separately violates the "Probably early expiration" algorithm.
$value = $cache
->psr()
->get('myKey');
When using \Yiisoft\Cache\Cache
, additionally to TTL for getOrSet()
method you can specify a dependency
that may trigger cache invalidation. Below is an example using tag dependency:
/**
* @var callable $callable
* @var \Yiisoft\Cache\CacheInterface $cache
*/
use Yiisoft\Cache\Dependency\TagDependency;
// Set multiple cache values marking both with a tag.
$cache->getOrSet('item_42_price', $callable, null, new TagDependency('item_42'));
$cache->getOrSet('item_42_total', $callable, 3600, new TagDependency('item_42'));
// Trigger invalidation by tag.
TagDependency::invalidate($cache, 'item_42');
Other dependencies:
Yiisoft\Cache\Dependency\CallbackDependency
- invalidates the cache when callback result changes.Yiisoft\Cache\Dependency\FileDependency
- invalidates the cache based on file modification time.Yiisoft\Cache\Dependency\ValueDependency
- invalidates the cache when specified value changes.
You may combine multiple dependencies using Yiisoft\Cache\Dependency\AnyDependency
or Yiisoft\Cache\Dependency\AllDependencies
.
In order to implement your own dependency extend from Yiisoft\Cache\Dependency\Dependency
.
A cache stampede is a type of cascading failure that can occur when massively
parallel computing systems with caching mechanisms come under very high load. This behaviour is sometimes also called dog-piling.
The \Yiisoft\Cache\Cache
uses a built-in "Probably early expiration" algorithm that prevents cache stampede.
This algorithm randomly fakes a cache miss for one user while others are still served the cached value.
You can control its behavior with the fifth optional parameter of getOrSet()
, which is a float value called $beta
.
By default, beta is 1.0
, which is sufficient in most cases. The higher the value the earlier cache will be re-created.
/**
* @var mixed $key
* @var callable $callable
* @var \DateInterval $ttl
* @var \Yiisoft\Cache\CacheInterface $cache
* @var \Yiisoft\Cache\Dependency\Dependency $dependency
*/
$beta = 2.0;
$cache->getOrSet($key, $callable, $ttl, $dependency, $beta);
Below the handler refers to the implementations of PSR-16.
This package contains two handlers:
Yiisoft\Cache\ArrayCache
- provides caching for the current request only by storing the values in an array.Yiisoft\Cache\NullCache
- does not cache anything reporting success for all methods calls.
Extra cache handlers are implemented as separate packages:
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
The Yii Caching Library is free software. It is released under the terms of the BSD License.
Please see LICENSE
for more information.
Maintained by Yii Software.