// boilerplate code example with Memcached...
$client = new \Memcached();
$client->addServer('localhost', 11211);
// create Scrapbook KeyValueStore object
$cache = new \MatthiasMullie\Scrapbook\Adapters\Memcached($client);

// set a value
$cache->set('key', 'value'); // returns true

// get a value
$cache->get('key'); // returns 'value'

KeyValueStore is the cornerstone of this project. It is the interface that provides the most cache operations: get, getMulti, set, setMulti, delete, deleteMulti, add, replace, cas, increment, decrement, touch & flush.

If you’ve ever used Memcached before, KeyValueStore will look very similar, since it’s inspired by/modeled after that API.

All adapters & features implement this interface. If you have complex cache needs (like being able to cas), this is the one to stick to.

Methods

get($key, &$token = null): mixed|bool

Retrieves an item from the cache.

Optionally, an 2nd variable can be passed to this function. It will be filled with a value that can be used for cas()

getMulti(array $keys, array &$tokens = null): mixed[]

Retrieves multiple items at once.

Return value will be an associative array in [key => value] format. Keys missing in cache will be omitted from the array.

Optionally, an 2nd variable can be passed to this function. It will be filled with values that can be used for cas(), in an associative array in [key => token] format. Keys missing in cache will be omitted from the array.

getMulti is preferred over multiple individual get operations as you'll get them all in 1 request.

set($key, $value, $expire = 0): bool

Stores a value, regardless of whether or not the key already exists (in which case it will overwrite the existing value for that key)

Return value is a boolean true when the operation succeeds, or false on failure.

setMulti(array $items, $expire = 0): bool[]

Store multiple values at once.

Return value will be an associative array in [key => status] form, where status is a boolean true for success, or false for failure.

setMulti is preferred over multiple individual set operations as you'll set them all in 1 request.

delete($key): bool

Deletes an item from the cache.
Returns true if item existed & was successfully deleted, false otherwise.

Return value is a boolean true when the operation succeeds, or false on failure.

deleteMulti(array $keys): bool[]

Deletes multiple items at once (reduced network traffic compared to individual operations)

Return value will be an associative array in [key => status] form, where status is a boolean true for success, or false for failure.

add($key, $value, $expire = 0): bool

Adds an item under new key.

This operation fails (returns false) if the key already exists in cache. If the operation succeeds, true will be returned.

replace($key, $value, $expire = 0): bool

Replaces an item.

This operation fails (returns false) if the key does not yet exist in cache. If the operation succeeds, true will be returned.

cas($token, $key, $value, $expire = 0): bool

Replaces an item in 1 atomic operation, to ensure it didn't change since it was originally read, when the CAS token was issued.

This operation fails (returns false) if the CAS token didn't match with what's currently in cache, when a new value has been written to cache after we've fetched it. If the operation succeeds, true will be returned.

increment($key, $offset = 1, $initial = 0, $expire = 0): int|bool

Increments a counter value, or sets an initial value if it does not yet exist.

The new counter value will be returned if this operation succeeds, or false for failure (e.g. when the value currently in cache is not a number, in which case it can't be incremented)

decrement($key, $offset = 1, $initial = 0, $expire = 0): int|bool

Decrements a counter value, or sets an initial value if it does not yet exist.

The new counter value will be returned if this operation succeeds, or false for failure (e.g. when the value currently in cache is not a number, in which case it can't be decremented)

touch($key, $expire): bool

Updates an item's expiration time without altering the stored value.

Return value is a boolean true when the operation succeeds, or false on failure.

flush(): bool

Clears the entire cache.

getCollection(): KeyValueStore

Returns an isolated subset (collection) in which to store or fetch data from.

A new KeyValueStore object will be returned, one that will only have access to this particular subset of data. Exact implementation can vary between adapters (e.g. separate database, prefixed keys, ...), but it will only ever provide access to data within this collection.

It is not possible to set/fetch data across collections.
Setting the same key in 2 different collections will store 2 different values, that can only be retrieved from their respective collections.
Flushing a collection will only flush those specific keys and will leave keys in other collections untouched.
Flushing the server, however, will wipe out everything, including data in any of the collections on that server.