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:

Configuration

There are two ways to get cache instance. If you need PSR-16 instance, you can simply create it:

In order to set a global key prefix:

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:

Set a default TTL:

General usage

Typical PSR-16 cache usage is the following:

In order to delete value you can use:

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:

Normalization of the key occurs using the Yiisoft\Cache\CacheKeyNormalizer.

In order to delete value you can use:

You can use PSR-16 methods the following way, but remember that getting and setting the cache separately violates the "Probably early expiration" algorithm.

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:

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.

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:

• APCu
• Database
• File
• Memcached
• Redis
• Wincache

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:

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.

Support the project

Follow updates