Scrapbook

KeyValueStore

Interface for key-value storage engines.

Tags
author

Matthias Mullie [email protected]

copyright

Copyright (c) 2014, Matthias Mullie. All rights reserved.

license

LICENSE MIT

Table of Contents

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) : 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

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
bool

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, string $key, mixed $value, int $expire) : 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

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
bool

decrement()

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

public decrement(string $key[, int $offset = 1 ], int $initial, int $expire) : 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

Initial value (if item doesn't yet exist)

$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

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
bool

deleteMulti()

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
bool

get()

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, int $expire) : 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

Initial value (if item doesn't yet exist)

$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

Return values
int|bool

New value or false on failure

replace()

Replaces an item.

public replace(string $key, mixed $value, int $expire) : 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

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
bool

set()

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) : bool

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

Parameters
$key : string
$value : mixed
$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

Return values
bool

setMulti()

Store multiple values at once.

public setMulti(array<string|int, mixed> $items, int $expire) : 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

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

Return values
bool

Search results