BufferedStore
in package
implements
KeyValueStore
This class will serve as a local buffer to the real cache: anything read from & written to the real cache will be stored in memory, so if any of those keys is again requested in the same request, we can just grab it from memory instead of having to get it over the wire.
Tags
Table of Contents
Interfaces
- KeyValueStore
- Interface for key-value storage engines.
Methods
- __construct() : mixed
- add() : bool
- Adds an item under new key.
- cas() : 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.
- decrement() : int|false
- Decrements a counter value, or sets an initial value if it does not yet exist.
- delete() : bool
- Deletes an item from the cache.
- deleteMulti() : array<string|int, bool>
- Deletes multiple items at once (reduced network traffic compared to individual operations).
- flush() : bool
- Clears the entire cache (or the everything for the given collection).
- get() : mixed|bool
- In addition to all writes being stored to $local, we'll also keep get() values around ;).
- getCollection() : KeyValueStore
- Returns an isolated subset (collection) in which to store or fetch data from.
- getMulti() : array<string|int, mixed>
- In addition to all writes being stored to $local, we'll also keep get() values around ;).
- increment() : int|false
- Increments a counter value, or sets an initial value if it does not yet exist.
- replace() : bool
- Replaces an item.
- set() : 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).
- setMulti() : array<string|int, bool>
- Store multiple values at once.
- touch() : bool
- Updates an item's expiration time without altering the stored value.
Methods
__construct()
public
__construct(KeyValueStore $cache) : mixed
Parameters
- $cache : KeyValueStore
-
The real cache we'll buffer for
add()
Adds an item under new key.
public
add(string $key, mixed $value[, int $expire = 0 ]) : bool
This operation fails (returns false) if the key already exists in cache. If the operation succeeds, true will be returned.
Parameters
- $key : string
- $value : mixed
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
boolcas()
Replaces an item in 1 atomic operation, to ensure it didn't change since it was originally read, when the CAS token was issued.
public
cas(mixed $token, string $key, mixed $value[, int $expire = 0 ]) : bool
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.
Parameters
- $token : mixed
-
Token received from get() or getMulti()
- $key : string
- $value : mixed
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
booldecrement()
Decrements a counter value, or sets an initial value if it does not yet exist.
public
decrement(string $key[, int $offset = 1 ][, int $initial = 0 ][, int $expire = 0 ]) : int|false
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)
Parameters
- $key : string
- $offset : int = 1
-
Value to decrement with
- $initial : int = 0
-
Initial value (if item doesn't yet exist)
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
int|false —New value or false on failure
delete()
Deletes an item from the cache.
public
delete(string $key) : bool
Returns true if item existed & was successfully deleted, false otherwise.
Return value is a boolean true when the operation succeeds, or false on failure.
Parameters
- $key : string
Return values
booldeleteMulti()
Deletes multiple items at once (reduced network traffic compared to individual operations).
public
deleteMulti(array<string|int, mixed> $keys) : array<string|int, bool>
Return value will be an associative array in [key => status] form, where status is a boolean true for success, or false for failure.
Parameters
- $keys : array<string|int, mixed>
Return values
array<string|int, bool>flush()
Clears the entire cache (or the everything for the given collection).
public
flush() : bool
Return value is a boolean true when the operation succeeds, or false on failure.
Return values
boolget()
In addition to all writes being stored to $local, we'll also keep get() values around ;).
public
get(string $key[, mixed &$token = null ]) : mixed|bool
Parameters
- $key : string
- $token : mixed = null
-
Will be filled with the CAS token
Return values
mixed|bool —Value, or false on failure
getCollection()
Returns an isolated subset (collection) in which to store or fetch data from.
public
getCollection(string $name) : KeyValueStore
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.
Parameters
- $name : string
Return values
KeyValueStore —A new KeyValueStore instance representing only a subset of data on this server
getMulti()
In addition to all writes being stored to $local, we'll also keep get() values around ;).
public
getMulti(array<string|int, mixed> $keys[, array<string|int, mixed>|null &$tokens = null ]) : array<string|int, mixed>
Parameters
- $keys : array<string|int, mixed>
- $tokens : array<string|int, mixed>|null = null
-
Will be filled with the CAS tokens, in [key => token] format
Return values
array<string|int, mixed> —[key => value]
increment()
Increments a counter value, or sets an initial value if it does not yet exist.
public
increment(string $key[, int $offset = 1 ][, int $initial = 0 ][, int $expire = 0 ]) : int|false
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)
Parameters
- $key : string
- $offset : int = 1
-
Value to increment with
- $initial : int = 0
-
Initial value (if item doesn't yet exist)
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
int|false —New value or false on failure
replace()
Replaces an item.
public
replace(string $key, mixed $value[, int $expire = 0 ]) : bool
This operation fails (returns false) if the key does not yet exist in cache. If the operation succeeds, true will be returned.
Parameters
- $key : string
- $value : mixed
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
boolset()
Stores a value, regardless of whether or not the key already exists (in which case it will overwrite the existing value for that key).
public
set(string $key, mixed $value[, int $expire = 0 ]) : bool
Return value is a boolean true when the operation succeeds, or false on failure.
Parameters
- $key : string
- $value : mixed
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
boolsetMulti()
Store multiple values at once.
public
setMulti(array<string|int, mixed> $items[, int $expire = 0 ]) : array<string|int, bool>
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.
Parameters
- $items : array<string|int, mixed>
-
[key => value]
- $expire : int = 0
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp
Return values
array<string|int, bool>touch()
Updates an item's expiration time without altering the stored value.
public
touch(string $key, int $expire) : bool
Return value is a boolean true when the operation succeeds, or false on failure.
Parameters
- $key : string
- $expire : int
-
Time when item falls out of the cache: 0 = permanent (doesn't expires); under 2592000 (30 days) = relative time, in seconds from now; over 2592000 = absolute time, unix timestamp