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:

Data serialization

The package provides Yiisoft\Cache\Serializer\SerializerInterface for data serialization. It can be useful in database, file or Redis cache implementations. Out of box, you can use Yiisoft\Cache\Serializer\PhpSerializer that works via PHP functions serialize() and unserialize(). You can make own implementation, for example:

use Yiisoft\Cache\Serializer\SerializerInterface;

final class IgbinarySerializer implements SerializerInterface 
{
    public function serialize(mixed $value) : string
    {
        return igbinary_serialize($value);
    }

    public function unserialize(string $data) : mixed
    {
        return igbinary_unserialize($data);
    }
}

Documentation

Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

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.

yiisoft / cache

Maintainers

Details