Fr3nch13/CakePHP Utilities

FileEngine extends CacheEngine
in package

Application

File Storage engine for cache. Filestorage is the slowest cache storage to read and write. However, it is good for servers that don't have other storage engine available, or have content which is not performance sensitive.

You can configure a FileEngine cache, using Cache::config()

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 config used unless overridden by runtime configuration
$_File : SplFileObject|null: Instance of SplFileObject class
$_groupPrefix : string: Contains the compiled string with all group prefixes to be prepended to every key in this cache engine
$_init : bool: True unless FileEngine::__active(); fails

Methods

add() : bool: Add a key to the cache if it does not already exist.
clear() : bool: Delete all values from the cache
clearGroup() : bool: Recursively deletes all files under any directory named as $group
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: Not implemented
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>: 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: Not implemented
init() : bool: Initialize File 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.
_active() : bool: Determine if cache directory is writable
_clearDirectory() : void: Used to clear a directory of matching files.
_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.
_setKey() : bool: Sets the current cache key this class is managing, and creates a writable SplFileObject for the cache file the key is referring to.
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 config used unless overridden by runtime configuration


    protected
        array<string, mixed>
    $_defaultConfig
     = ['duration' => 3600, 'groups' => [], 'lock' => true, 'mask' => 0664, 'path' => null, 'prefix' => 'cake_', 'serialize' => 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.
lock Used by FileCache. Should files be locked before writing to them?
mask The mask used for created files
path Path to where cachefiles should be saved. Defaults to system's temp dir.
prefix Prepended to all entries. Good for when you need to share a keyspace with either another cache config or another application. cache::gc from ever being called automatically.
serialize Should cache objects be serialized first.

$_File

Instance of SplFileObject class


    protected
        SplFileObject|null
    $_File

$_groupPrefix

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


    protected
        string
    $_groupPrefix
     = ''

$_init

True unless FileEngine::__active(); fails


    protected
        bool
    $_init
     = true

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 values from the cache


    public
                    clear() : bool

Return values

bool —

True if the cache was successfully cleared, false otherwise

clearGroup()

Recursively deletes all files under any directory named as $group


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

Not implemented


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

Parameters

$key : string: The key to decrement
$offset : int = 1: The number to offset

Return values

int|false

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

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

Not implemented


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

Parameters

$key : string: The key to increment
$offset : int = 1: The number to offset

Return values

int|false

init()

Initialize File 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

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.

_active()

Determine if cache directory is writable


    protected
                    _active() : bool

Return values

bool

_clearDirectory()

Used to clear a directory of matching files.


    protected
                    _clearDirectory(string $path) : void

Parameters

$path : string: The path to search.

_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(mixed $key) : string

Parameters

$key : mixed: the key passed over

Return values

string —

Prefixed key with potentially unsafe characters replaced.

_setKey()

Sets the current cache key this class is managing, and creates a writable SplFileObject for the cache file the key is referring to.


    protected
                    _setKey(string $key[, bool $createKey = false ]) : bool

Parameters

$key : string: The key
$createKey : bool = false: Whether the key should be created if it doesn't exists, or not

Return values

bool —

true if the cache key could be set, false otherwise

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.

FileEngine extends CacheEngine in package Application

Table of Contents

Constants

Properties

Methods

Constants

CHECK_KEY

CHECK_VALUE

Properties

$_config

$_configInitialized

$_defaultConfig

$_File

$_groupPrefix

$_init

Methods

add()

Parameters

Return values

clear()

Return values

clearGroup()

Parameters

Return values

configShallow()

Parameters

Return values

decrement()

Parameters

Tags

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

Tags

Return values

init()

Parameters

Return values

set()

Parameters

Return values

setConfig()

Usage

Parameters

Tags

Return values

setMultiple()

Parameters

Tags

Return values

_active()

Return values

FileEngine extends CacheEngine
in package

Application