Fr3nch13/CakePHP Utilities

ArrayEngine extends CacheEngine
in package

Application

Array storage engine for cache.

Not actually a persistent cache engine. All data is only stored in memory for the duration of a single process. While not useful in production settings this engine can be useful in tests or console tools where you don't want the overhead of interacting with a cache servers, but want the work saving properties a cache provides.

Constants

CHECK_KEY = 'key'
CHECK_VALUE = 'value'

Properties

$_config : array<string, mixed>: Runtime config
$_configInitialized : bool: Whether the config property has already been configured with defaults
$_defaultConfig : array<string, mixed>: The default cache configuration is overridden in most cache adapters. These are the keys that are common to all adapters. If overridden, this property is not used.
$_groupPrefix : string: Contains the compiled string with all group prefixes to be prepended to every key in this cache engine
$data : array<string, array<string|int, mixed>>: Cached data.

Methods

add() : bool: Add a key to the cache if it does not already exist.
clear() : bool: Delete all keys from the cache. This will clear every cache config using APC.
clearGroup() : bool: Increments the group value to simulate deletion of all keys under a group old values will remain in storage until they expire.
configShallow() : $this: Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.
decrement() : int|false: Decrements the value of an integer cached key
delete() : bool: Delete a key from the cache
deleteMultiple() : bool: Deletes multiple cache items as a list
get() : mixed: Read a key from the cache
getConfig() : mixed: Returns the config.
getConfigOrFail() : mixed: Returns the config for this specific key.
getMultiple() : iterable<string|int, mixed>: Obtains multiple cache items by their unique keys.
groups() : array<string|int, string>: Returns the `group value` for each of the configured groups If the group initial value was not found, then it initializes the group accordingly.
has() : bool: Determines whether an item is present in the cache.
increment() : int|false: Increments the value of an integer cached key
init() : bool: Initialize the cache engine
set() : bool: Write data for key into cache
setConfig() : $this: Sets the config.
setMultiple() : bool: Persists a set of key => value pairs in the cache, with an optional TTL.
_configDelete() : void: Deletes a single config key.
_configRead() : mixed: Reads a config key.
_configWrite() : void: Writes a config key.
_key() : string: Generates a key for cache backend usage.
duration() : int: Convert the various expressions of a TTL value into duration in seconds
ensureValidKey() : void: Ensure the validity of the given cache key.
ensureValidType() : void: Ensure the validity of the argument type and cache keys.
warning() : void: Cache Engines may trigger warnings if they encounter failures during operation, if option warnOnWriteFailures is set to true.

CHECK_KEY


    protected
        string
    CHECK_KEY
    = 'key'

CHECK_VALUE


    protected
        string
    CHECK_VALUE
    = 'value'

$_config

Runtime config


    protected
        array<string, mixed>
    $_config
     = []

$_configInitialized

Whether the config property has already been configured with defaults


    protected
        bool
    $_configInitialized
     = false

$_defaultConfig

The default cache configuration is overridden in most cache adapters. These are the keys that are common to all adapters. If overridden, this property is not used.


    protected
        array<string, mixed>
    $_defaultConfig
     = ['duration' => 3600, 'groups' => [], 'prefix' => 'cake_', 'warnOnWriteFailures' => true]

duration Specify how long items in this cache configuration last.
groups List of groups or 'tags' associated to every key stored in this config. handy for deleting a complete group from cache.
prefix Prefix appended to all entries. Good for when you need to share a keyspace with either another cache config or another application.
warnOnWriteFailures Some engines, such as ApcuEngine, may raise warnings on write failures.

$_groupPrefix

Contains the compiled string with all group prefixes to be prepended to every key in this cache engine


    protected
        string
    $_groupPrefix
     = ''

$data

Cached data.


    protected
        array<string, array<string|int, mixed>>
    $data
     = []

Structured as [key => [exp => expiration, val => value]]

add()

Add a key to the cache if it does not already exist.


    public
                    add(string $key, mixed $value) : bool

Defaults to a non-atomic implementation. Subclasses should prefer atomic implementations.

Parameters

$key : string: Identifier for the data.
$value : mixed: Data to be cached.

Return values

bool —

True if the data was successfully cached, false on failure.

clear()

Delete all keys from the cache. This will clear every cache config using APC.


    public
                    clear() : bool

Return values

bool —

True Returns true.

clearGroup()

Increments the group value to simulate deletion of all keys under a group old values will remain in storage until they expire.


    public
                    clearGroup(string $group) : bool

Parameters

$group : string: The group to clear.

Return values

bool —

success

configShallow()

Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.


    public
                    configShallow(array<string, mixed>|string $key[, mixed|null $value = null ]) : $this

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

$key : array<string, mixed>|string: The key to set, or a complete array of configs.
$value : mixed|null = null: The value to set.

Return values

$this

decrement()

Decrements the value of an integer cached key


    public
                    decrement(string $key[, int $offset = 1 ]) : int|false

Parameters

$key : string: Identifier for the data
$offset : int = 1: How much to subtract

Return values

int|false —

New decremented value, false otherwise

delete()

Delete a key from the cache


    public
                    delete(string $key) : bool

Parameters

$key : string: Identifier for the data

Return values

bool —

True if the value was successfully deleted, false if it didn't exist or couldn't be removed

deleteMultiple()

Deletes multiple cache items as a list


    public
                    deleteMultiple(iterable<string|int, mixed> $keys) : bool

This is a best effort attempt. If deleting an item would create an error it will be ignored, and all items will be attempted.

Parameters

$keys : iterable<string|int, mixed>: A list of string-based keys to be deleted.

Return values

bool —

True if the items were successfully removed. False if there was an error.

get()

Read a key from the cache


    public
                    get(string $key[, mixed $default = null ]) : mixed

Parameters

$key : string: Identifier for the data
$default : mixed = null: Default value to return if the key does not exist.

Return values

mixed —

The cached data, or default value if the data doesn't exist, has expired, or if there was an error fetching it.

getConfig()

Returns the config.


    public
                    getConfig([string|null $key = null ][, mixed $default = null ]) : mixed

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

$key : string|null = null: The key to get or null for the whole config.
$default : mixed = null: The return value when the key does not exist.

Return values

mixed —

Configuration data at the named key or null if the key does not exist.

getConfigOrFail()

Returns the config for this specific key.


    public
                    getConfigOrFail(string $key) : mixed

The config value for this key must exist, it can never be null.

Parameters

$key : string: The key to get.

Return values

mixed —

Configuration data at the named key

getMultiple()

Obtains multiple cache items by their unique keys.


    public
                    getMultiple(iterable<string|int, mixed> $keys[, mixed $default = null ]) : iterable<string|int, mixed>

Parameters

$keys : iterable<string|int, mixed>: A list of keys that can obtained in a single operation.
$default : mixed = null: Default value to return for keys that do not exist.

Return values

iterable<string|int, mixed> —

A list of key value pairs. Cache keys that do not exist or are stale will have $default as value.

groups()

Returns the `group value` for each of the configured groups If the group initial value was not found, then it initializes the group accordingly.


    public
                    groups() : array<string|int, string>

Return values

array<string|int, string>

has()

Determines whether an item is present in the cache.


    public
                    has(string $key) : bool

NOTE: It is recommended that has() is only to be used for cache warming type purposes and not to be used within your live applications operations for get/set, as this method is subject to a race condition where your has() will return true and immediately after, another script can remove it making the state of your app out of date.

Parameters

$key : string: The cache item key.

Return values

bool

increment()

Increments the value of an integer cached key


    public
                    increment(string $key[, int $offset = 1 ]) : int|false

Parameters

$key : string: Identifier for the data
$offset : int = 1: How much to increment

Return values

int|false —

New incremented value, false otherwise

init()

Initialize the cache engine


    public
                    init([array<string, mixed> $config = [] ]) : bool

Called automatically by the cache frontend. Merge the runtime config with the defaults before use.

Parameters

$config : array<string, mixed> = []: Associative array of parameters for the engine

Return values

bool —

True if the engine has been successfully initialized, false if not

set()

Write data for key into cache


    public
                    set(string $key, mixed $value[, DateInterval|int|null $ttl = null ]) : bool

Parameters

$key : string: Identifier for the data
$value : mixed: Data to be cached
$ttl : DateInterval|int|null = null: Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Return values

bool —

True on success and false on failure.

setConfig()

Sets the config.


    public
                    setConfig(array<string, mixed>|string $key[, mixed|null $value = null ][, bool $merge = true ]) : $this

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

$key : array<string, mixed>|string: The key to set, or a complete array of configs.
$value : mixed|null = null: The value to set.
$merge : bool = true: Whether to recursively merge or overwrite existing config, defaults to true.

Return values

$this

setMultiple()

Persists a set of key => value pairs in the cache, with an optional TTL.


    public
                    setMultiple(iterable<string|int, mixed> $values[, DateInterval|int|null $ttl = null ]) : bool

Parameters

$values : iterable<string|int, mixed>: A list of key => value pairs for a multiple-set operation.
$ttl : DateInterval|int|null = null: Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Return values

bool —

True on success and false on failure.

_configDelete()

Deletes a single config key.


    protected
                    _configDelete(string $key) : void

Parameters

$key : string: Key to delete.

_configRead()

Reads a config key.


    protected
                    _configRead(string|null $key) : mixed

Parameters

$key : string|null: Key to read.

_configWrite()

Writes a config key.


    protected
                    _configWrite(array<string, mixed>|string $key, mixed $value[, string|bool $merge = false ]) : void

Parameters

$key : array<string, mixed>|string: Key to write to.
$value : mixed: Value to write.
$merge : string|bool = false: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

_key()

Generates a key for cache backend usage.


    protected
                    _key(string $key) : string

If the requested key is valid, the group prefix value and engine prefix are applied. Whitespace in keys will be replaced.

Parameters

$key : string: the key passed over

Return values

string —

Prefixed key with potentially unsafe characters replaced.

duration()

Convert the various expressions of a TTL value into duration in seconds


    protected
                    duration(DateInterval|int|null $ttl) : int

Parameters

$ttl : DateInterval|int|null: The TTL value of this item. If null is sent, the driver's default duration will be used.

Return values

int

ensureValidKey()

Ensure the validity of the given cache key.


    protected
                    ensureValidKey(string $key) : void

Parameters

$key : string: Key to check.

ensureValidType()

Ensure the validity of the argument type and cache keys.


    protected
                    ensureValidType(iterable<string|int, mixed> $iterable[, string $check = self::CHECK_VALUE ]) : void

Parameters

$iterable : iterable<string|int, mixed>: The iterable to check.
$check : string = self::CHECK_VALUE: Whether to check keys or values.

warning()

Cache Engines may trigger warnings if they encounter failures during operation, if option warnOnWriteFailures is set to true.


    protected
                    warning(string $message) : void

Parameters

$message : string: The warning message.

ArrayEngine extends CacheEngine in package Application

Table of Contents

Constants

Properties

Methods

Constants

CHECK_KEY

CHECK_VALUE

Properties

$_config

$_configInitialized

$_defaultConfig

$_groupPrefix

$data

Methods

add()

Parameters

Return values

clear()

Return values

clearGroup()

Parameters

Return values

configShallow()

Parameters

Return values

decrement()

Parameters

Return values

delete()

Parameters

Return values

deleteMultiple()

Parameters

Tags

Return values

get()

Parameters

Return values

getConfig()

Usage

Parameters

Return values

getConfigOrFail()

Parameters

Tags

Return values

getMultiple()

Parameters

Tags

Return values

groups()

Return values

has()

Parameters

Tags

Return values

increment()

Parameters

Return values

init()

Parameters

Return values

set()

Parameters

Return values

setConfig()

Usage

Parameters

Tags

Return values

setMultiple()

Parameters

Tags

Return values

_configDelete()

Parameters

Tags

_configRead()

Parameters

ArrayEngine extends CacheEngine
in package

Application