Async, Promise-based cache interface for ReactPHP.

The cache component provides a Promise-based CacheInterface and an in-memory ArrayCache implementation of that. This allows consumers to type hint against the interface and third parties to provide alternate implementations.

Table of Contents

• Usage
  • CacheInterface
    • get()
    • set()
    • delete()
  • ArrayCache
• Common usage
  • Fallback get
  • Fallback-get-and-set
• Install
• Tests
• License

The CacheInterface describes the main interface of this component. This allows consumers to type hint against the interface and third parties to provide alternate implementations.

The get(string $key, mixed $default = null): PromiseInterface method can be used to retrieve an item from the cache.

This method will resolve with the cached value on success or with the given $default value when no item can be found or when an error occurs. Similarly, an expired cache item (once the time-to-live is expired) is considered a cache miss.

$cache
    ->get('foo')
    ->then('var_dump');

This example fetches the value of the key foo and passes it to the var_dump function. You can use any of the composition provided by promises.

The set(string $key, mixed $value, ?float $ttl = null): PromiseInterface method can be used to store an item in the cache.

This method will resolve with true on success or false when an error occurs. If the cache implementation has to go over the network to store it, it may take a while.

The optional $ttl parameter sets the maximum time-to-live in seconds for this cache item. If this parameter is omitted (or null), the item will stay in the cache for as long as the underlying implementation supports. Trying to access an expired cache item results in a cache miss, see also get().

$cache->set('foo', 'bar', 60);

This example eventually sets the value of the key foo to bar. If it already exists, it is overridden.

Deletes an item from the cache.

This method will resolve with true on success or false when an error occurs. When no item for $key is found in the cache, it also resolves to true. If the cache implementation has to go over the network to delete it, it may take a while.

$cache->delete('foo');

This example eventually deletes the key foo from the cache. As with set(), this may not happen instantly and a promise is returned to provide guarantees whether or not the item has been removed from cache.

The ArrayCache provides an in-memory implementation of the CacheInterface.

$cache = new ArrayCache();

$cache->set('foo', 'bar');

Its constructor accepts an optional ?int $limit parameter to limit the maximum number of entries to store in the LRU cache. If you add more entries to this instance, it will automatically take care of removing the one that was least recently used (LRU).

For example, this snippet will overwrite the first value and only store the last two entries:

$cache = new ArrayCache(2);

$cache->set('foo', '1');
$cache->set('bar', '2');
$cache->set('baz', '3');

A common use case of caches is to attempt fetching a cached value and as a fallback retrieve it from the original data source if not found. Here is an example of that:

$cache
    ->get('foo')
    ->then(function ($result) {
        if ($result === null) {
            return getFooFromDb();
        }
        
        return $result;
    })
    ->then('var_dump');

First an attempt is made to retrieve the value of foo. A callback function is registered that will call getFooFromDb when the resulting value is null. getFooFromDb is a function (can be any PHP callable) that will be called if the key does not exist in the cache.

getFooFromDb can handle the missing key by returning a promise for the actual value from the database (or any other data source). As a result, this chain will correctly fall back, and provide the value in both cases.

To expand on the fallback get example, often you want to set the value on the cache after fetching it from the data source.

$cache
    ->get('foo')
    ->then(function ($result) {
        if ($result === null) {
            return $this->getAndCacheFooFromDb();
        }
        
        return $result;
    })
    ->then('var_dump');

public function getAndCacheFooFromDb()
{
    return $this->db
        ->get('foo')
        ->then(array($this, 'cacheFooFromDb'));
}

public function cacheFooFromDb($foo)
{
    $this->cache->set('foo', $foo);

    return $foo;
}

By using chaining you can easily conditionally cache the value if it is fetched from the database.

The recommended way to install this library is through Composer. New to Composer?

This will install the latest supported version:

$ composer require react/cache:^0.5.0

See also the CHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 7+ and HHVM. It's highly recommended to use PHP 7+ for this project.

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

$ composer install

To run the test suite, go to the project root and run:

$ php vendor/bin/phpunit

MIT, see LICENSE file.