Class Cache

Provides a cache for arbitrary data and driver-based storage. Cache entries are identified by a class and key that together form a unique hash. Additionally, a timestamp is stored with each entry and optionally a maximum age, after which entries are deleted.

To avoid corrupt data, cache entries are stored with the version ID of the cache instance (defaults to the framework revision). A version ID must match for a cache entry to be fetched. After upgrading a system, it is recommended to clean up old cache entries if no older version of the system is still running.

A default cache instance is transparently used by system functions. This can either be configured via the Core\Configuration\CacheFilesTarget configuration constant or an existing driver instance can be set as default via Core\Cache::activate().

Core\Object implements Core\Chainable

Core\Set implements Core\Accessor

Core\Cache

Direct known subclasses

Core\Cache\Driver\apc, Core\Cache\Driver\file, Core\Cache\Driver\null, Core\Cache\Driver\storage

Abstract
Namespace: Core
Package: Core\Cache
Since: 3.0
Requires: PHP 5.3
Version: 1.2
Located at Cache.inc.php

Methods summary

`public`	# `__construct( Core\URI $uri )` Parameters `$uri` Driver configuration URI. Since 3.0
`public static`	# `activate( Core\Cache $cache )` Activates a new default cache. Activates a new default cache. Parameters `$cache` Cache instance to replace currently active cache with. Since 3.0
`public static Core\Cache`	# `active( )` Returns the currently active cache instance. If no cache instance is active, the default instance is activated and returned. Returns the currently active cache instance. If no cache instance is active, the default instance is activated and returned. Returns `Core\Cache` The currently active cache instance. Throws `Core\Exception\Configuration` Failed to initialise default system cache. All cache targets failed. See `Core\Cache::defaultInstance()` Since 3.0
`public static Core\Cache`	# `autocreate( Core\URI $uri )` Cache factory. Cache factory. Parameters `$uri` Driver configuration URI. Returns `Core\Cache` Since 3.0
`public static Core\Cache`	# `defaultInstance( )` Returns the default cache instance. The default cache instance is configured by defining several cache targets using the `Core\Configuration\CacheFilesTarget` constant; if no such constant is defined, the global temporary target will be used instead. The first successfully initialised cache target is returned and cached for further requests; if all cache targets fail, an exception is thrown. Returns the default cache instance. The default cache instance is configured by defining several cache targets using the `Core\Configuration\CacheFilesTarget` constant; if no such constant is defined, the global temporary target will be used instead. The first successfully initialised cache target is returned and cached for further requests; if all cache targets fail, an exception is thrown. Returns `Core\Cache` The default Cache instance. Throws `Core\Exception\Configuration` All cache targets failed. Since 3.0
`abstract public boolean`	# `exists( string $class, string $key )` Tests, whether a cache entry for a class item exists. Tests, whether a cache entry for a class item exists. Parameters `$class` Cache class of item to test for. `$key` The item key to test for. Returns boolean `true`, if a cache entry for the requested item exists, otherwise `false`. Since 3.0
`public string`	# `get( string $class, string $key )` Reads a cache entry and returns all binary data for the entry. Reads a cache entry and returns all binary data for the entry. Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns string Binary data string of cache entry. Remark The default implementation fetches a stream reader for the requested item and reads all remaining stream segments that are afterwards returned. Driver should override this method if they internally are not stream-based for a more efficient implementation. Since 3.0
`public integer`	# `getAge( string $class, string $key )` Returns age of cache entry (since last modification). Returns age of cache entry (since last modification). Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns integer Age in seconds of cache entry since last modification. Since 3.1
`public string`	# `getHash( string $class, string $key )` Returns the hash for the requested cache entry. The hash type depends on the backend in use and defaults to 16-byte binary MD5. Returns the hash for the requested cache entry. The hash type depends on the backend in use and defaults to 16-byte binary MD5. Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns string Binary hash of cache element. Remark Drivers can optionally store the hash with the cached value and then should override this method to return the stored hash. Since 3.1
`public array`	# `getMeta( string $class, string $key )` Returns an array of meta attributes for the requested cache entry. Returns an array of meta attributes for the requested cache entry. Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns array Associative array of the following cache entry meta attributes: age hash timestamp (since of last modification) Since 3.1
`abstract public Core\Stream`	# `getStream( string $class, string $key )` Returns a reading stream instance for the requested cache entry. Returns a reading stream instance for the requested cache entry. Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns `Core\Stream` Reading Stream instance for the requested cache entry. Since 3.0
`abstract public integer`	# `getTimestamp( string $class, string $key )` Returns a UNIX timestamp of the last cache entry modification. Returns a UNIX timestamp of the last cache entry modification. Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns integer UNIX timestamp of last modification to the named cache entry. Since 3.1
`public mixed`	# `getVar( string $class, string $key )` Reads a serialized data entry from the cache. Reads a serialized data entry from the cache. Parameters `$class` Class of cache item. `$key` The key of the cache item. Returns mixed De-serialised variable from the cache or `null`, if no such cache entry exists (or was `null` when created). Since 3.0
`public`	# `put( string $class, string $key, string $binaryData, integer $ttl = null )` Writes binary data to a specified cache entry. Writes binary data to a specified cache entry. Parameters `$class` Class of cache item. `$key` The key of the cache item. `$binaryData` Binary data string to write to the cache entry. `$ttl` Time to live for cache entry (in seconds). Set to `null` if entry does not timeout. Remark Any existing cache entry will be overwritten without further notice. The default implementation is based on the stream writing interface. Drivers that are not internally stream-based should override this method for a more efficient implementation. Since 3.0
`abstract public Core\Stream`	# `putStream( string $class, string $key, integer $ttl = null )` Returns a writing stream instance for the requested cache entry. Returns a writing stream instance for the requested cache entry. Parameters `$class` Class of cache item. `$key` The key of the cache item. `$ttl` Time to live for cache entry (in seconds). Set to `null` if entry does not timeout. Returns `Core\Stream` Writing Stream instance for the requested cache entry. Remark The returned `Core\Stream` instance is established using the Stream::Truncate and Stream::Create flags. Since 3.0
`public`	# `putVar( string $class, string $key, mixed $value, integer $ttl = null )` Writes a variable serialized to a specified cache entry. Writes a variable serialized to a specified cache entry. Parameters `$class` Class of cache item. `$key` The key of the cache item. `$value` Variable to serialize and store as cache entry. `$ttl` Time to live for cache entry (in seconds). Set to `null` if entry does not timeout. Since 3.0
`abstract public`	# `remove( string $class, string $key )` Deletes a cache key entry. If the entry does not exist, no operation is performed. Deletes a cache key entry. If the entry does not exist, no operation is performed. Parameters `$class` Class of cache item. `$key` The key of the cache item. Since 3.1
`public integer`	# `setVersionID( integer $versionID )` Sets the automatically appended numeric subclass for data entries. Sets the automatically appended numeric subclass for data entries. Parameters `$versionID` The new numeric subclass to use (e.g. the application revision number). Returns integer Previously set version ID. Remark Automatic numeric subclasses are used to allow different versions of an application to use the same cache back-end without interfering each other or resulting in errors due to changed data structures. Since 3.0
`public static string`	# `unify( string\|string[] $properties )` Returns a unique cache key from a set of item properties. Returns a unique cache key from a set of item properties. Parameters `$properties` Item properties to create hash from. Accepts either a binary string or an array of strings. The properties parameter should include all information to uniquely identify the item or item group. Returns string Unique cache key of 40 byte length calculated from presented item properties. The cache key is guaranteed to only contain hexadecimal characters for utmost compatibility with different cache mechanisms. Since 3.1

Methods inherited from Core\Set

__get(), __isset()

Methods inherited from Core\Object

__autocreateFactory(), __call(), __processParameters(), __toString(), attachMethod(), chain(), getValueForKey(), getValueForKeyPath(), getValueForUndefinedKey(), hash(), issetValueForKey(), setValueForKey(), setValueForKeyPath(), setValueForUndefinedKey(), uuid()

Constants summary

`string`	`SharedClass` Predefined name of shared cache class. Predefined name of shared cache class. Since 3.0	# `'Shared'`

Constants inherited from Core\Object

AnyParameterType, AutochainParameterType, AutocreateParameterType, BooleanParameterType, CharParameterType, EnumParameterType, IntegerParameterType, RealParameterType, StringParameterType, UserParameterType

Properties summary

`public static Core\Cache`	`$_activeInstance` Activated default cache instance. Activated default cache instance. Since 3.0	#
`protected integer`	`$_v_versionID` Version ID of cache entries. Version ID of cache entries. Since 3.0	#

Magic properties

`public read-only integer`	`$versionID` Configured version ID cache entries are assigned to.

Magic properties inherited from Core\Object

$hash, $uuid

Namespaces

Classes

Interfaces

Exceptions

Constants

Class Cache

Direct known subclasses

Methods summary

Parameters

Since

Parameters

Since

Returns

Throws

See

Since

Parameters

Returns

Since

Returns

Throws

Since

Parameters

Returns

Since

Parameters

Returns

Remark

Since

Parameters

Returns

Since

Parameters

Returns

Remark

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Remark

Since

Parameters

Returns

Remark

Since

Parameters

Since

Parameters

Since

Parameters

Returns

Remark

Since

Parameters

Returns

Since

Methods inherited from Core\Set

Methods inherited from Core\Object

Constants summary

Since

Constants inherited from Core\Object

Properties summary

Since

Since

Magic properties

Magic properties inherited from Core\Object