Shard
in package
implements
KeyValueStore
This class lets you scale your cache cluster by sharding the data across multiple cache servers.
Pass the individual KeyValueStore objects that compose the cache server pool into this constructor how you want the data to be sharded. The cache data will be sharded over them according to the order they were in when they were passed into this constructor (so make sure to always keep the order the same)
The sharding is spread evenly and all cache servers will roughly receive the same amount of cache keys. If some servers are bigger than others, you can offset this by adding the KeyValueStore object more than once.
Data can even be sharded among different adapters: one server in the shard pool can be Redis while another can be Memcached. Not sure why you would even want that, but you could!
Tags
Table of Contents
Interfaces
- KeyValueStore
- Interface for key-value storage engines.
Methods
- __construct() : mixed
- Overloadable with multiple KeyValueStore objects.
- add() : bool
- Adds an item under new key.
- addCache() : mixed
- 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
__construct()
Overloadable with multiple KeyValueStore objects.
public
__construct(KeyValueStore $cache1[, KeyValueStore|null $cache2 = null ]) : mixed
Parameters
- $cache1 : KeyValueStore
- $cache2 : KeyValueStore|null = null
add()
Adds an item under new key.
public
add(mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $key : mixed
- $value : mixed
- $expire : mixed = 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
booladdCache()
public
addCache(KeyValueStore $cache) : mixed
Parameters
- $cache : KeyValueStore
cas()
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, mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $token : mixed
-
Token received from get() or getMulti()
- $key : mixed
- $value : mixed
- $expire : mixed = 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(mixed $key[, mixed $offset = 1 ][, mixed $initial = 0 ][, mixed $expire = 0 ]) : int|bool
Parameters
- $key : mixed
- $offset : mixed = 1
-
Value to decrement with
- $initial : mixed = 0
-
Initial value (if item doesn't yet exist)
- $expire : mixed = 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(mixed $key) : bool
Parameters
- $key : mixed
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>
Parameters
- $keys : array<string|int, mixed>
Return values
array<string|int, bool>flush()
Clears the entire cache.
public
flush() : bool
Return values
boolget()
Retrieves an item from the cache.
public
get(mixed $key[, mixed &$token = null ]) : mixed|bool
Parameters
- $key : mixed
- $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>
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(mixed $key[, mixed $offset = 1 ][, mixed $initial = 0 ][, mixed $expire = 0 ]) : int|bool
Parameters
- $key : mixed
- $offset : mixed = 1
-
Value to increment with
- $initial : mixed = 0
-
Initial value (if item doesn't yet exist)
- $expire : mixed = 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(mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $key : mixed
- $value : mixed
- $expire : mixed = 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(mixed $key, mixed $value[, mixed $expire = 0 ]) : bool
Parameters
- $key : mixed
- $value : mixed
- $expire : mixed = 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[, mixed $expire = 0 ]) : array<string|int, bool>
Parameters
- $items : array<string|int, mixed>
-
[key => value]
- $expire : mixed = 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(mixed $key, mixed $expire) : bool
Parameters
- $key : mixed
- $expire : mixed
-
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