Scrapbook

Buffer extends MemoryStore
in package

Scrapbook

This is a helper class for BufferedStore & TransactionalStore, which buffer real cache requests in memory.

The memory-part can easily be handled by MemoryStore. There's just 1 gotcha: when an item is to be deleted (but not yet committed), it needs to be deleted from the MemoryStore too, but we need to be able to make a distinction between "this is deleted" and "this value is not known in this memory cache, fall back to real cache".

This is where this class comes in to play: we'll add an additional "expired" method, which allows BufferedStore to just expire the keys that are supposed to be deleted (instead of deleting them) - then we can keep track of when a key is just not known, or known-but-deleted (=expired)

Properties

$items : array<string|int, mixed>

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).
expired() : bool: Check if a key existed in local storage, but is now expired.
flush() : bool: Clears the entire cache (or the everything for the given collection).
get() : mixed|bool: Retrieves an item from the cache.
getCollection() : KeyValueStore: Returns an isolated subset (collection) in which to store or fetch data from.
getMulti() : array<string|int, mixed>: Retrieves multiple items at once.
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.

$items


    public
        array<string|int, mixed>
    $items
     = []

__construct()


    public
                    __construct([int|string|null $limit = null ]) : mixed

Parameters

$limit : int|string|null = null: Memory limit in bytes (defaults to 10% of memory_limit)

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

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 = 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

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 = 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

bool

deleteMulti()

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>

expired()

Check if a key existed in local storage, but is now expired.


    public
                    expired(string $key) : bool

Because our local buffer is also just a real cache, expired items will just return nothing, which will lead us to believe no such item exists in that local cache, and we'll reach out to the real cache (where the value may not yet have been expired because that may have been part of an uncommitted write) So we'll want to know when a value is in local cache, but expired!

Parameters

$key : string

Return values

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

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

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

Retrieves multiple items at once.


    public
                    getMulti(array<string|int, mixed> $keys[, array<string|int, mixed>|null &$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 = 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

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 = 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

bool

setMulti()

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

Return values

bool

Buffer extends MemoryStore in package Scrapbook

Tags

Table of Contents

Properties

Methods

Properties

$items

Methods

__construct()

Parameters

add()

Parameters

Return values

cas()

Parameters

Return values

decrement()

Parameters

Return values

delete()

Parameters

Return values

deleteMulti()

Parameters

Return values

expired()

Parameters

Return values

flush()

Return values

get()

Parameters

Return values

getCollection()

Parameters

Return values

getMulti()

Parameters

Return values

increment()

Parameters

Return values

replace()

Parameters

Return values

set()

Parameters

Return values

setMulti()

Parameters

Return values

touch()

Parameters

Return values

Buffer extends MemoryStore
in package

Scrapbook