yiisoft / cache
Yii Caching Library
Fund package maintenance!
Opencollective
yiisoft
Installs: 448 806
Dependents: 60
Suggesters: 1
Security: 0
Stars: 31
Watchers: 19
Forks: 19
Open Issues: 2
Requires
- php: ^8.0
- ext-json: *
- ext-mbstring: *
- psr/simple-cache: ^2.0|^3.0
Requires (Dev)
- maglnet/composer-require-checker: ^4.2
- phpunit/phpunit: ^9.5
- rector/rector: ^0.15.2
- roave/infection-static-analysis-plugin: ^1.16
- spatie/phpunit-watcher: ^1.23
- vimeo/psalm: ^4.30|^5.6
- yiisoft/di: ^1.2
Suggests
- yiisoft/cache-apcu: Allows to store cache using APCu PECL extension
- yiisoft/cache-db: Allows storing cache to the database
- yiisoft/cache-file: Allows storing cache to the files
- yiisoft/cache-memcached: Allows to store cache using Memcached PECL extension
- yiisoft/cache-redis: Allows storing cache to the Redis
- yiisoft/cache-wincache: Allows to store cache using WinCache PECL extension
Provides
- psr/simple-cache-implementation: 2.0|3.0
This package is auto-updated.
Last update: 2023-06-05 21:11:42 UTC
README
Yii Caching Library
This library is a wrapper around PSR-16 compatible caching libraries providing own features. It is used in Yii Framework but is usable separately.
Features
- 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.
Requirements
- PHP 8.0 or higher.
JSON
PHP extension.Mbstring
PHP extension.
Installation
The package could be installed with composer:
composer require yiisoft/cache
Configuration
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
General usage
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');
Invalidation dependencies
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
.
Cache stampede prevention
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);
Cache handlers
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:
Testing
Unit testing
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
Mutation testing
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
Static analysis
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
License
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.