Fr3nch13/CakePHP Utilities

CacheEngine
in package

Application

implements CacheInterface, CacheEngineInterface uses InstanceConfigTrait

AbstractYes

Storage engine for CakePHP caching

Interfaces

CacheInterface
CacheEngineInterface: Interface for cache engines that defines methods outside of the PSR16 interface that are used by `Cache`.

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

Methods

add() : bool: Add a key to the cache if it does not already exist.
clear() : bool: Delete all keys from the cache
clearGroup() : bool: Clears all values belonging to a group. Is up to the implementing engine to decide whether actually delete the keys or just simulate it to achieve the same result.
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: Decrement a number under the key and return decremented value
delete() : bool: Delete a key from the cache
deleteMultiple() : bool: Deletes multiple cache items as a list
get() : mixed: Fetches the value for a given 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>: Does whatever initialization for each group is required and returns the `group value` for each of them, this is the token representing each group in the cache key
has() : bool: Determines whether an item is present in the cache.
increment() : int|false: Increment a number under the key and return incremented value
init() : bool: Initialize the cache engine
set() : bool: Persists data in the cache, uniquely referenced by the given key with an optional expiration TTL time.
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
     = ''

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


    public
    abstract                clear() : bool

Return values

bool —

True if the cache was successfully cleared, false otherwise

clearGroup()

Clears all values belonging to a group. Is up to the implementing engine to decide whether actually delete the keys or just simulate it to achieve the same result.


    public
    abstract                clearGroup(string $group) : bool

Parameters

$group : string: name of the group to be cleared

Return values

bool

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

Decrement a number under the key and return decremented value


    public
    abstract                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 incremented value, false otherwise

delete()

Delete a key from the cache


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

Fetches the value for a given key from the cache.


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

Parameters

$key : string: The unique key of this item in the cache.
$default : mixed = null: Default value to return if the key does not exist.

Return values

mixed —

The value of the item from the cache, or $default in case of cache miss.

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

Does whatever initialization for each group is required and returns the `group value` for each of them, this is the token representing each group in the cache key


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

Increment a number under the key and return incremented value


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

Parameters

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

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

Persists data in the cache, uniquely referenced by the given key with an optional expiration TTL time.


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

Parameters

$key : string: The key of the item to store.
$value : mixed: The value of the item to store, must be serializable.
$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.

CacheEngine in package Application implements CacheInterface, CacheEngineInterface uses InstanceConfigTrait

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

CHECK_KEY

CHECK_VALUE

Properties

$_config

$_configInitialized

$_defaultConfig

$_groupPrefix

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

Tags

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

Tags

Return values

setConfig()

Usage

Parameters

Tags

Return values

setMultiple()

Parameters

Tags

Return values

_configDelete()

Parameters

Tags

CacheEngine
in package

Application

implements CacheInterface, CacheEngineInterface uses InstanceConfigTrait