KeyValueStore
in
Interface for key-value storage engines.
Tags
Table of Contents
Methods
- 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|bool
- 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.
- get() : mixed|bool
- Retrieves an item from the cache.
- getMulti() : array<string|int, mixed>
- Retrieves multiple items at once.
- increment() : int|bool
- 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
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|bool
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|bool —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, string> $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, string>
Return values
array<string|int, bool>flush()
Clears the entire cache.
public
flush() : bool
Return value is a boolean true when the operation succeeds, or false on failure.
Return values
boolget()
Retrieves an item from the cache.
public
get(string $key[, mixed &$token = null ]) : mixed|bool
Optionally, an 2nd variable can be passed to this function. It will be filled with a value that can be used for cas()
Parameters
- $key : string
- $token : mixed = null
-
Will be filled with the CAS token
Return values
mixed|bool —Value, or false on failure
getMulti()
Retrieves multiple items at once.
public
getMulti(array<string|int, mixed> $keys[, array<string|int, mixed> &$tokens = null ]) : array<string|int, mixed>
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.
Parameters
- $keys : array<string|int, mixed>
- $tokens : array<string|int, mixed> = 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|bool
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|bool —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