Documentation

CacheInterface

Table of Contents

Methods

clear()  : PromiseInterface<string|int, bool>
Wipes clean the entire cache.
delete()  : PromiseInterface<string|int, bool>
Deletes an item from the cache.
deleteMultiple()  : PromiseInterface<string|int, bool>
Deletes multiple cache items in a single operation.
get()  : PromiseInterface<string|int, mixed>
Retrieves an item from the cache.
getMultiple()  : PromiseInterface<string|int, array<string|int, mixed>>
Retrieves multiple cache items by their unique keys.
has()  : PromiseInterface<string|int, bool>
Determines whether an item is present in the cache.
set()  : PromiseInterface<string|int, bool>
Stores an item in the cache.
setMultiple()  : PromiseInterface<string|int, bool>
Persists a set of key => value pairs in the cache, with an optional TTL.

Methods

delete()

Deletes an item from the cache.

public delete(string $key) : PromiseInterface<string|int, bool>

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.

Parameters
$key : string
Return values
PromiseInterface<string|int, bool>

Returns a promise which resolves to true on success or false on error

deleteMultiple()

Deletes multiple cache items in a single operation.

public deleteMultiple(array<string|int, string> $keys) : PromiseInterface<string|int, bool>
Parameters
$keys : array<string|int, string>

A list of string-based keys to be deleted.

Return values
PromiseInterface<string|int, bool>

Returns a promise which resolves to true on success or false on error

get()

Retrieves an item from the cache.

public get(string $key[, mixed $default = null ]) : PromiseInterface<string|int, mixed>

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.

Parameters
$key : string
$default : mixed = null

Default value to return for cache miss or null if not given.

Return values
PromiseInterface<string|int, mixed>

getMultiple()

Retrieves multiple cache items by their unique keys.

public getMultiple(array<string|int, string> $keys[, mixed $default = null ]) : PromiseInterface<string|int, array<string|int, mixed>>

This method will resolve with an array of cached values on success or with the given $default value when an item can not 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->getMultiple(array('name', 'age'))->then(function (array $values) {
    $name = $values['name'] ?? 'User';
    $age = $values['age'] ?? 'n/a';

    echo $name . ' is ' . $age . PHP_EOL;
});

This example fetches the cache items for the name and age keys and prints some example output. You can use any of the composition provided by promises.

Parameters
$keys : array<string|int, string>

A list of keys that can obtained in a single operation.

$default : mixed = null

Default value to return for keys that do not exist.

Return values
PromiseInterface<string|int, array<string|int, mixed>>

Returns a promise which resolves to an array of cached values

has()

Determines whether an item is present in the cache.

public has(string $key) : PromiseInterface<string|int, bool>

This method will resolve with true on success or false 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
    ->has('foo')
    ->then('var_dump');

This example checks if the value of the key foo is set in the cache and passes the result to the var_dump function. You can use any of the composition provided by promises.

NOTE: It is recommended that has() is only to be used for cache warming type purposes and not to be used within your live applications operations for get/set, as this method is subject to a race condition where your has() will return true and immediately after, another script can remove it making the state of your app out of date.

Parameters
$key : string

The cache item key.

Return values
PromiseInterface<string|int, bool>

Returns a promise which resolves to true on success or false on error

set()

Stores an item in the cache.

public set(string $key, mixed $value[, float|null $ttl = null ]) : PromiseInterface<string|int, bool>

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.

This interface does not enforce any particular TTL resolution, so special care may have to be taken if you rely on very high precision with millisecond accuracy or below. Cache implementations SHOULD work on a best effort basis and SHOULD provide at least second accuracy unless otherwise noted. Many existing cache implementations are known to provide microsecond or millisecond accuracy, but it's generally not recommended to rely on this high precision.

This interface suggests that cache implementations SHOULD use a monotonic time source if available. Given that a monotonic time source is only available as of PHP 7.3 by default, cache implementations MAY fall back to using wall-clock time. While this does not affect many common use cases, this is an important distinction for programs that rely on a high time precision or on systems that are subject to discontinuous time adjustments (time jumps). This means that if you store a cache item with a TTL of 30s and then adjust your system time forward by 20s, the cache item SHOULD still expire in 30s.

Parameters
$key : string
$value : mixed
$ttl : float|null = null
Return values
PromiseInterface<string|int, bool>

Returns a promise which resolves to true on success or false on error

setMultiple()

Persists a set of key => value pairs in the cache, with an optional TTL.

public setMultiple(array<string|int, mixed> $values[, float|null $ttl = null ]) : PromiseInterface<string|int, bool>

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 these cache items. If this parameter is omitted (or null), these items will stay in the cache for as long as the underlying implementation supports. Trying to access an expired cache items results in a cache miss, see also get().

$cache->setMultiple(array('foo' => 1, 'bar' => 2), 60);

This example eventually sets the list of values - the key foo to 1 value and the key bar to 2. If some of the keys already exist, they are overridden.

Parameters
$values : array<string|int, mixed>

A list of key => value pairs for a multiple-set operation.

$ttl : float|null = null

Optional. The TTL value of this item.

Return values
PromiseInterface<string|int, bool>

Returns a promise which resolves to true on success or false on error


        
On this page

Search results