Fr3nch13/CakePHP Utilities

MemcachedEngine extends CacheEngine
in package

Application

Memcached storage engine for cache. Memcached has some limitations in the amount of control you have over expire times far in the future. See MemcachedEngine::write() for more information.

Memcached engine supports binary protocol and igbinary serialization (if memcached extension is compiled with --enable-igbinary). Compressed keys can also be incremented/decremented.

Constants

CHECK_KEY = 'key'
CHECK_VALUE = 'value'

Properties

$_compiledGroupNames : array<string|int, string>
$_config : array<string, mixed>: Runtime config
$_configInitialized : bool: Whether the config property has already been configured with defaults
$_defaultConfig : array<string, mixed>: The default config used unless overridden by runtime configuration
$_groupPrefix : string: Contains the compiled string with all group prefixes to be prepended to every key in this cache engine
$_Memcached : Memcached: memcached wrapper.
$_serializers : array<string, int>: List of available serializer engines

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: 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: Delete many keys from the cache at once
get() : mixed: Read a key from the cache
getConfig() : mixed: Returns the config.
getConfigOrFail() : mixed: Returns the config for this specific key.
getMultiple() : array<string|int, mixed>: Read many keys from the cache at once
getOption() : string|int|bool|null: Read an option value from the memcached connection.
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
parseServerString() : array<string|int, mixed>: Parses the server address into the host/port. Handles both IPv6 and IPv4 addresses and Unix sockets
set() : bool: Write data for key into cache. When using memcached as your cache engine remember that the Memcached pecl extension does not support cache expiry times greater than 30 days in the future. Any duration greater than 30 days will be treated as real Unix time value rather than an offset from current time.
setConfig() : $this: Sets the config.
setMultiple() : bool: Write many cache entries to the cache at once
_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.
_setOptions() : void: Settings the memcached instance
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'

$_compiledGroupNames


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

$_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 config used unless overridden by runtime configuration


    protected
        array<string, mixed>
    $_defaultConfig
     = ['compress' => false, 'duration' => 3600, 'groups' => [], 'host' => null, 'username' => null, 'password' => null, 'persistent' => null, 'port' => null, 'prefix' => 'cake_', 'serialize' => 'php', 'servers' => ['127.0.0.1'], 'options' => []]

compress Whether to compress data
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.
username Login to access the Memcache server
password Password to access the Memcache server
persistent The name of the persistent connection. All configurations using the same persistent value will share a single underlying connection.
prefix Prepended to all entries. Good for when you need to share a keyspace with either another cache config or another application.
serialize The serializer engine used to serialize data. Available engines are 'php', 'igbinary' and 'json'. Beside 'php', the memcached extension must be compiled with the appropriate serializer support.
servers String or array of memcached servers. If an array MemcacheEngine will use them as a pool.
options - Additional options for the memcached client. Should be an array of option => value. Use the \Memcached::OPT_* constants as keys.

$_groupPrefix

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


    protected
        string
    $_groupPrefix
     = ''

$_Memcached

memcached wrapper.


    protected
        Memcached
    $_Memcached

$_serializers

List of available serializer engines


    protected
        array<string, int>
    $_serializers
     = []

Memcached must be compiled with JSON and igbinary support to use these engines

add()

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


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

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

Return values

bool —

True if the cache was successfully cleared, false otherwise

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: name of the group to be cleared

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

Delete many keys from the cache at once


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

Parameters

$keys : iterable<string|int, mixed>: An array of identifiers for the data

Return values

bool —

of boolean values that are true if the key was successfully deleted, false if it didn't exist or couldn't be removed.

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

Read many keys from the cache at once


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

Parameters

$keys : iterable<string|int, mixed>: An array of identifiers for the data
$default : mixed = null: Default value to return for keys that do not exist.

Return values

array<string|int, mixed> —

An array containing, for each of the given $keys, the cached data or false if cached data could not be retrieved.

getOption()

Read an option value from the memcached connection.


    public
                    getOption(int $name) : string|int|bool|null

Parameters

$name : int: The option name to read.

Return values

string|int|bool|null

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

Parameters

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

Return values

bool —

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

parseServerString()

Parses the server address into the host/port. Handles both IPv6 and IPv4 addresses and Unix sockets


    public
                    parseServerString(string $server) : array<string|int, mixed>

Parameters

$server : string: The server address string.

Return values

array<string|int, mixed> —

Array containing host, port

set()

Write data for key into cache. When using memcached as your cache engine remember that the Memcached pecl extension does not support cache expiry times greater than 30 days in the future. Any duration greater than 30 days will be treated as real Unix time value rather than an offset from current time.


    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 if the data was successfully cached, 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()

Write many cache entries to the cache at once


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

Parameters

$values : iterable<string|int, mixed>: An array of data to be stored in the cache
$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 —

Whether the write was successful or not.

_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.

_setOptions()

Settings the memcached instance


    protected
                    _setOptions() : void

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.

MemcachedEngine extends CacheEngine in package Application

Table of Contents

Constants

Properties

Methods

Constants

CHECK_KEY

CHECK_VALUE

Properties

$_compiledGroupNames

$_config

$_configInitialized

$_defaultConfig

$_groupPrefix

$_Memcached

$_serializers

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

Return values

get()

Parameters

Return values

getConfig()

Usage

Parameters

Return values

getConfigOrFail()

Parameters

Tags

Return values

getMultiple()

Parameters

Return values

getOption()

Parameters

Tags

Return values

groups()

Return values

has()

Parameters

Tags

Return values

increment()

Parameters

Return values

init()

Parameters

Tags

Return values

parseServerString()

Parameters

Return values

set()

Parameters

Tags

Return values

setConfig()

Usage

Parameters

Tags

Return values

MemcachedEngine extends CacheEngine
in package

Application