Download the PHP package kuria/cache without Composer

Cache #####

Caching library with driver abstraction.

:depth: 3

Features

• entry operations: has, add, set, get, delete
• multiple-entry operations: getting, setting, adding, deleting
• listing, filtering, cleanup (requires driver support)
• TTL expiration
• key prefixing / namespacing
• stored and retrieved values can be manipulated via events
• PSR-6 cache adapter
• PSR-16 simple cache wrapper
• multiple built-in driver implementations

Requirements

• PHP 7.1+

Built-in drivers

Usage

Creating a cache instance

Filesystem

Store cache entries in the given directory as binary files.

$driver = new FilesystemDriver(__DIR . '/cache'); $cache = new Cache($driver);

Storing cache entries as PHP files

It may be beneficial to store cache entries as actual PHP files (instead of binary ones), so that they may be picked up by opcode caches (e.g. opcache) to increase performance.

$driver = new FilesystemDriver( __DIR . '/cache', FilesystemDriver::createEntryFactory(new PhpFileFormat()) );

$cache = new Cache($driver);

APCu

Store cache entries using APCu.

$cache = new Cache(new ApcuDriver());

Memcached

Store cache entries using Memcached.

$memcached = new \Memcached(); $memcached->addServer('localhost', 11211);

$cache = new Cache(new MemcachedDriver($memcached));

Redis

Store cache entries using PhpRedis.

$redis = new \Redis(); $redis->connect('localhost', 6380); // might return FALSE..

$cache = new Cache(new RedisDriver($redis));

Memory

Store cache entries in memory.

These entries are only available for the duration of the script and aren't shared between threads.

$cache = new Cache(new MemoryDriver());

Black hole

Stored entries are discarded immediately. Useful for testing or debugging.

$cache = new Cache(new BlackHoleDriver());

Cache methods

setPrefix() - configure cache prefix

The setPefix() method defines a prefix that will be applied to all keys before they are passed to the underlying driver implementation.

The prefix can be an empty string to disable this functionality.

getNamespace() - get a namespaced cache instance

The getNamespace() method returns a cache instance that applies a prefix to all keys before passing them to the original cache.

$fooCache->get('bar'); // reads foo.bar $fooCache->delete('baz'); // deletes foo.baz $fooCache->clear(); // deletes foo.* (if the cache is filterable) // etc.

has() - check if an entry exists

The has() method returns TRUE or FALSE indicating whether the entry exists or not.

If you need to distinguish between a NULL value and a nonexistent entry, use the $exists argument:

if ($exists) { // entry was found // $value might be NULL if NULL was stored } else { // entry was not found }

getMultiple() - read multiple entries

The getMultiple() method returns a key-value map. Nonexistent keys will have a NULL value.

If you need to distinguish between NULL values and a nonexistent entries, use the $failedKeys argument:

// $failedKeys will contain a list of keys that were not found

listKeys() - list keys in the cache

The listKeys() method will return an iterable list of keys in the cache, optionally matching a common prefix.

If the driver doesn't support this operation, an UnsupportedOperationException exception will be thrown. You can check support using the isFilterable() method.

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

TTL (time-to-live in seconds) can be specified using the third argument:

$cache->add('bar', 'bar-value', 120);

If TTL is NULL, 0 or negative, the entry will not have an expiration time.

addMultiple() / setMultiple() - create multiple entries

The addMultiple() and setMultiple() methods both create multiple entries in the cache.

The setMultiple() method will overwrite any existing entries with the same keys, but addMultiple() will not.

See Allowed value types.

$cache->setMultiple(['foo' => 'foo-value', 'bar' => 'bar-value']);

TTL (time-to-live in seconds) can be specified using the second argument:

$cache->setMultiple(['foo' => 'foo-value', 'bar' => 'bar-value'], 120);

If TTL is NULL, 0 or negative, the entries will not have expiration times.

cached() - cache the result of a callback

The cached() method tries to read a value from the cache. If it does not exist, it invokes the given callback and caches its return value (even if it is NULL).

return $result;

delete() - delete an entry

The delete() method deletes a single entry from the cache.

cleanup() - clean-up the cache

Some cache drivers (e.g. FilesystemDriver) support explicit triggering of the cleanup procedures (removal of expired entries etc).

If the driver doesn't support this operation, an UnsupportedOperationException exception will be thrown. You can check support using the supportsCleanup() method.

$cache->on(CacheEvents::HIT, function (string $key, $value) { printf( "Read key %s from the cache, the value is %s\n", $key, var_export($value, true) ); });

CacheEvents::MISS

Emitted when an entry has not been found.

The listener is passed the key.

$cache->on(CacheEvents::MISS, function (string $key) { echo "The key {$key} was not found in the cache\n"; });

CacheEvents::WRITE

Emitted when an entry is about to be written.

The listener is passed the key, value, TTL and overwrite flag.

$cache->on(CacheEvents::WRITE, function (string $key, $value, ?int $ttl, bool $overwrite) { printf( "Writing key %s to the cache, with TTL = %s, overwrite = %s and value = %s\n", $key, var_export($ttl, true), var_export($overwrite, true), var_export($value, true) ); });

CacheEvents::DRIVER_EXCEPTION

Emitted when the underlying driver implementation throws an exception.

The listener is passed the exception object. This can be used for debugging or logging purposes.

$cache->on(CacheEvents::DRIVER_EXCEPTION, function (\Throwable $e) { echo 'Driver exception: ', $e; });

PSR-6: Cache adapter

The CacheItemPool class is an adapter implementing the Psr\Cache\CacheItemPoolInterface.

To use it, you need to have psr/cache (^1.0) installed.

See http://www.php-fig.org/psr/psr-6/ for more information.

$pool = new CacheItemPool($cache);

Also see Creating a cache instance.

PSR-16: Simple cache wrapper

The SimpleCache class is a wrapper implementing the Psr\SimpleCache\CacheInterface.

To use it, you need to have psr/simple-cache (^1.0) installed.

See http://www.php-fig.org/psr/psr-16/ for more information.

$simpleCache = new SimpleCache($cache);

Also see Creating a cache instance.