Zend\Cache\Storage\Adapter¶

Overview¶

Storage adapters are wrappers for real storage resources such as memory and the filesystem, using the well known adapter pattern.

They comes with tons of methods to read, write and modify stored items and to get information about stored items and the storage.

All adapters implements the interface Zend\Cache\Storage\StorageInterface and most extend Zend\Cache\Storage\Adapter\AbstractAdapter, which comes with basic logic.

Configuration is handled by either Zend\Cache\Storage\Adapter\AdapterOptions, or an adapter-specific options class if it exists. You may pass the options instance to the class at instantiation or via the setOptions() method, or alternately pass an associative array of options in either place (internally, these are then passed to an options class instance). Alternately, you can pass either the options instance or associative array to the Zend\Cache\StorageFactory::factory method.

Note

Many methods throw exceptions

Because many caching methods can throw exceptions, you need to catch them manually or you can use the plug-in Zend\Cache\Storage\Plugin\ExceptionHandler to automatically catch them and redirect exceptions into a log file using the option “exception_callback”.

Quick Start¶

Caching adapters can either be created from the provided Zend\Cache\StorageFactory factory, or by simply instantiating one of the Zend\Cache\Storage\Adapter\*classes.

To make life easier, the Zend\Cache\StorageFactory comes with a factory method to create an adapter and create/add all requested plugins at once.

use Zend\Cache\StorageFactory;

// Via factory:
$cache = StorageFactory::factory(array(
    'adapter' => 'apc',
    'plugins' => array(
        'exception_handler' => array('throw_exceptions' => false),
    ),
));

// Alternately:
$cache  = StorageFactory::adapterFactory('apc');
$plugin = StorageFactory::pluginFactory('exception_handler', array(
    'throw_exceptions' => false,
));
$cache->addPlugin($plugin);

// Or manually:
$cache  = new Zend\Cache\Storage\Adapter\Apc();
$plugin = new Zend\Cache\Storage\Plugin\ExceptionHandler(array(
    'throw_exceptions' => false,
));
$cache->addPlugin($plugin);

Basic configuration Options¶

Basic configuration is handled by either Zend\Cache\Storage\Adapter\AdapterOptions, or an adapter-specific options class if it exists. You may pass the options instance to the class at instantiation or via the setOptions() method, or alternately pass an associative array of options in either place (internally, these are then passed to an options class instance). Alternately, you can pass either the options instance or associative array to the Zend\Cache\StorageFactory::factory method.

The following configuration options are defined by Zend\Cache\Storage\Adapter\AdapterOptions and are available for every supported adapter. Adapter-specific configuration options are descriped on adapter level below.

Option Data Type Default Value Description

ttl integer 0 Time to live

namespace string “” The “namespace” in which cache items will live

key_pattern null string null Pattern against which to validate cache keys

readable boolean true Enable/Disable reading data from cache

writable boolean true Enable/Disable writing data to cache

Available Methods defined by `Zend\Cache\Storage\StorageInterface`¶

getItem

getItem(string $key, boolean & $success = null, mixed & $casToken = null)

Load an item with the given $key.

If item exists set parameter $success to true, set parameter $casToken and returns mixed value of item.

If item can’t load set parameter $success to false and returns null.

getItems

getItems(array $keys)

Load all items given by $keys.

Returns array of key-value pairs of available items.

hasItem

hasItem(string $key)

Test if an item exists.

Returns boolean

hasItems

hasItems(array $keys)

Test multiple items.

Returns array

getMetadata

getMetadata(string $key)

Get metadata of an item.

Returns array``|``boolean

getMetadatas

getMetadatas(array $keys)

Get multiple metadata.

Returns array

setItem

setItem(string $key, mixed $value)

Store an item.

Returns boolean

setItems

setItems(array $keyValuePairs)

Store multiple items.

Returns boolean

addItem

addItem(string $key, mixed $value)

Add an item.

Returns boolean

addItems

addItems(array $keyValuePairs)

Add multiple items.

Returns boolean

replaceItem

replaceItem(string $key, mixed $value)

Replace an item.

Returns boolean

replaceItems

replaceItems(array $keyValuePairs)

Replace multiple items.

Returns boolean

checkAndSetItem

checkAndSetItem(mixed $token, string $key, mixed $value)

Set item only if token matches. It uses the token received from getItem() to check if the item has changed before overwriting it.

Returns boolean

touchItem

touchItem(string $key)

Reset lifetime of an item.

Returns boolean

touchItems

touchItems(array $keys)

Reset lifetime of multiple items.

Returns boolean

removeItem

removeItem(string $key)

Remove an item.

Returns boolean

removeItems

removeItems(array $keys)

Remove multiple items.

Returns boolean

incrementItem

incrementItem(string $key, int $value)

Increment an item.

Returns integer``|``boolean

incrementItems

incrementItems(array $keyValuePairs)

Increment multiple items.

Returns boolean

decrementItem

decrementItem(string $key, int $value)

Decrement an item.

Returns interger``|``boolean

decrementItems

decrementItems(array $keyValuePairs)

Decrement multiple items.

Returns boolean

getCapabilities

getCapabilities()

Capabilities of this storage.

Returns Zend\Cache\Storage\Capabilities

Available Methods defined by `Zend\Cache\Storage\AvailableSpaceCapableInterface`¶

getAvailableSpace

getAvailableSpace()

Get available space in bytes.

Returns integer``|``float

Available Methods defined by `Zend\Cache\Storage\TotalSpaceCapableInterface`¶

getTotalSpace

getTotalSpace()

Get total space in bytes.

Returns integer``|``float

Available Methods defined by `Zend\Cache\Storage\ClearByNamespaceInterface`¶

clearByNamespace

clearByNamespace(string $namespace)

Remove items of given namespace.

Returns boolean

Available Methods defined by `Zend\Cache\Storage\ClearByPrefixInterface`¶

clearByPrefix

clearByPrefix(string $prefix)

Remove items matching given prefix.

Returns boolean

Available Methods defined by `Zend\Cache\Storage\ClearExpiredInterface`¶

clearExpired

clearExpired()

Remove expired items.

Returns boolean

Available Methods defined by `Zend\Cache\Storage\FlushableInterface`¶

flush

flush()

Flush the whole storage.

Returns boolean

Available Methods defined by `Zend\Cache\Storage\IterableInterface` (extends `IteratorAggregate`)¶

getIterator

getIterator()

Get an Iterator.

Returns Zend\Cache\Storage\IteratorInterface

Available Methods defined by `Zend\Cache\Storage\OptimizableInterface`¶

optimize

optimize()

Optimize the storage.

Returns boolean

Available Methods defined by `Zend\Cache\Storage\TaggableInterface`¶

setTags

setTags(string $key, string[] $tags)

Set tags to an item by given key. (An empty array will remove all tags)

Returns boolean

getTags

getTags(string $key)

Get tags of an item by given key.

Returns string[]``|``false

clearByTags

clearByTags(string[] $tags, boolean $disjunction = false)

Remove items matching given tags.

If $disjunction is true only one of the given tags must match else all given tags must match.

Returns boolean