Adapters

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

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

All adapters implement Zend\Cache\Storage\StorageInterface, and most extend Zend\Cache\Storage\Adapter\AbstractAdapter, which provides a foundation of common 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, 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.

Many Methods throw Exceptions

Because many caching operations throw an exception on error, you need to catch them. You can do so manually, or you can use the plugin Zend\Cache\Storage\Plugin\ExceptionHandler with throw_exceptions set to false to automatically catch them. You can also define an exception_callback to log exceptions.

Quick Start

Caching adapters can either be created from the provided Zend\Cache\StorageFactory, or by 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 all requested plugins at once.

use Zend\Cache\StorageFactory;

// Via factory:
$cache = StorageFactory::factory([
    'adapter' => [
        'name'    => 'apc',
        'options' => ['ttl' => 3600],
    ],
    'plugins' => [
        'exception_handler' => ['throw_exceptions' => false],
    ],
]);

// Alternately, create the adapter and plugin separately:
$cache  = StorageFactory::adapterFactory('apc', ['ttl' => 3600]);
$plugin = StorageFactory::pluginFactory('exception_handler', [
    'throw_exceptions' => false,
]);
$cache->addPlugin($plugin);

// Or do it completely manually:
$cache  = new Zend\Cache\Storage\Adapter\Apc();
$cache->getOptions()->setTtl(3600);

$plugin = new Zend\Cache\Storage\Plugin\ExceptionHandler();
$plugin->getOptions()->setThrowExceptions(false);
$cache->addPlugin($plugin);

Basic Configuration Options

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

The StorageInterface

Zend\Cache\Storage\StorageInterface is the basic interface implemented by all storage adapters.

namespace Zend\Cache\Storage;

use Traversable;

interface StorageInterface
{
    /**
     * Set options.
     *
     * [@param](https://github.com/param) array|Traversable|Adapter\AdapterOptions $options
     * [@return](https://github.com/return) StorageInterface Fluent interface
     */
    public function setOptions($options);

    /**
     * Get options
     *
     * [@return](https://github.com/return) Adapter\AdapterOptions
     */
    public function getOptions();

    /* reading */

    /**
     * Get an item.
     *
     * [@param](https://github.com/param)  string  $key
     * [@param](https://github.com/param)  bool $success
     * [@param](https://github.com/param)  mixed   $casToken
     * [@return](https://github.com/return) mixed Data on success, null on failure
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function getItem($key, & $success = null, & $casToken = null);

    /**
     * Get multiple items.
     *
     * [@param](https://github.com/param)  array $keys
     * [@return](https://github.com/return) array Associative array of keys and values
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function getItems(array $keys);

    /**
     * Test if an item exists.
     *
     * [@param](https://github.com/param)  string $key
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function hasItem($key);

    /**
     * Test multiple items.
     *
     * [@param](https://github.com/param)  array $keys
     * [@return](https://github.com/return) array Array of found keys
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function hasItems(array $keys);

    /**
     * Get metadata of an item.
     *
     * [@param](https://github.com/param)  string $key
     * [@return](https://github.com/return) array|bool Metadata on success, false on failure
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function getMetadata($key);

    /**
     * Get multiple metadata
     *
     * [@param](https://github.com/param)  array $keys
     * [@return](https://github.com/return) array Associative array of keys and metadata
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function getMetadatas(array $keys);

    /* writing */

    /**
     * Store an item.
     *
     * [@param](https://github.com/param)  string $key
     * [@param](https://github.com/param)  mixed  $value
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function setItem($key, $value);

    /**
     * Store multiple items.
     *
     * [@param](https://github.com/param)  array $keyValuePairs
     * [@return](https://github.com/return) array Array of not stored keys
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function setItems(array $keyValuePairs);

    /**
     * Add an item.
     *
     * [@param](https://github.com/param)  string $key
     * [@param](https://github.com/param)  mixed  $value
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function addItem($key, $value);

    /**
     * Add multiple items.
     *
     * [@param](https://github.com/param)  array $keyValuePairs
     * [@return](https://github.com/return) array Array of not stored keys
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function addItems(array $keyValuePairs);

    /**
     * Replace an existing item.
     *
     * [@param](https://github.com/param)  string $key
     * [@param](https://github.com/param)  mixed  $value
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function replaceItem($key, $value);

    /**
     * Replace multiple existing items.
     *
     * [@param](https://github.com/param)  array $keyValuePairs
     * [@return](https://github.com/return) array Array of not stored keys
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function replaceItems(array $keyValuePairs);

    /**
     * Set an item only if token matches
     *
     * It uses the token received from getItem() to check if the item has
     * changed before overwriting it.
     *
     * [@param](https://github.com/param)  mixed  $token
     * [@param](https://github.com/param)  string $key
     * [@param](https://github.com/param)  mixed  $value
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     * [@see](https://github.com/see)    getItem()
     * [@see](https://github.com/see)    setItem()
     */
    public function checkAndSetItem($token, $key, $value);

    /**
     * Reset lifetime of an item
     *
     * [@param](https://github.com/param)  string $key
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function touchItem($key);

    /**
     * Reset lifetime of multiple items.
     *
     * [@param](https://github.com/param)  array $keys
     * [@return](https://github.com/return) array Array of not updated keys
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function touchItems(array $keys);

    /**
     * Remove an item.
     *
     * [@param](https://github.com/param)  string $key
     * [@return](https://github.com/return) bool
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function removeItem($key);

    /**
     * Remove multiple items.
     *
     * [@param](https://github.com/param)  array $keys
     * [@return](https://github.com/return) array Array of not removed keys
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function removeItems(array $keys);

    /**
     * Increment an item.
     *
     * [@param](https://github.com/param)  string $key
     * [@param](https://github.com/param)  int    $value
     * [@return](https://github.com/return) int|bool The new value on success, false on failure
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function incrementItem($key, $value);

    /**
     * Increment multiple items.
     *
     * [@param](https://github.com/param)  array $keyValuePairs
     * [@return](https://github.com/return) array Associative array of keys and new values
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function incrementItems(array $keyValuePairs);

    /**
     * Decrement an item.
     *
     * [@param](https://github.com/param)  string $key
     * [@param](https://github.com/param)  int    $value
     * [@return](https://github.com/return) int|bool The new value on success, false on failure
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function decrementItem($key, $value);

    /**
     * Decrement multiple items.
     *
     * [@param](https://github.com/param)  array $keyValuePairs
     * [@return](https://github.com/return) array Associative array of keys and new values
     * [@throws](https://github.com/throws) \Zend\Cache\Exception\ExceptionInterface
     */
    public function decrementItems(array $keyValuePairs);

    /* status */

    /**
     * Capabilities of this storage
     *
     * [@return](https://github.com/return) Capabilities
     */
    public function getCapabilities();
}

The AvailableSpaceCapableInterface

Zend\Cache\Storage\AvailableSpaceCapableInterface implements a method to allow retrieving the current available space remaining in storage.

namespace Zend\Cache\Storage;

interface AvailableSpaceCapableInterface
{
    /**
     * Get available space in bytes
     *
     * [@return](https://github.com/return) int|float
     */
    public function getAvailableSpace();
}

The TotalSpaceCapableInterface

Zend\Cache\Storage\TotalSpaceCapableInterface implements a method to allow retrieving the total storage space.

namespace Zend\Cache\Storage;

interface TotalSpaceCapableInterface
{
    /**
     * Get total space in bytes
     *
     * [@return](https://github.com/return) int|float
     */
    public function getTotalSpace();
}

The ClearByNamespaceInterface

Zend\Cache\Storage\ClearByNamespaceInterface implements a method to allow clearing all cached items within a given namespace.

namespace Zend\Cache\Storage;

interface ClearByNamespaceInterface
{
    /**
     * Remove items of given namespace
     *
     * [@param](https://github.com/param) string $namespace
     * [@return](https://github.com/return) bool
     */
    public function clearByNamespace($namespace);
}

The ClearByPrefixInterface

Zend\Cache\Storage\ClearByPrefixInterface implements a method to allow clearing all cached items that have a given prefix (within the currently configured namespace).

namespace Zend\Cache\Storage;

interface ClearByPrefixInterface
{
    /**
     * Remove items matching given prefix
     *
     * [@param](https://github.com/param) string $prefix
     * [@return](https://github.com/return) bool
     */
    public function clearByPrefix($prefix);
}

The ClearExpiredInterface

Zend\Cache\Storage\ClearExpiredInterface implements a method to allow clearing all expired items (within the current configured namespace).

namespace Zend\Cache\Storage;

interface ClearExpiredInterface
{
    /**
     * Remove expired items
     *
     * [@return](https://github.com/return) bool
     */
    public function clearExpired();
}

The FlushableInterface

Zend\Cache\Storage\FlushableInterface implements a method for flushing the entire cache storage.

namespace Zend\Cache\Storage;

interface FlushableInterface
{
    /**
     * Flush the whole storage
     *
     * [@return](https://github.com/return) bool
     */
    public function flush();
}

The IterableInterface

Zend\Cache\Storage\IterableInterface implements a method for retrieving an iterator of all items in storage. It extends IteratorAggregate, so it's possible to directly iterate over the storage implementations that implement this interface using foreach.

namespace Zend\Cache\Storage;

use IteratorAggregate;

/**
 *
 * [@method](https://github.com/method) IteratorInterface getIterator() Get the storage iterator
 */
interface IterableInterface extends IteratorAggregate
{
    /**
     * [@return](https://github.com/return) \Traversable
     */
    public function getIterator();
}

The OptimizableInterface

Zend\Cache\Storage\OptimizableInterface implements a method for running optimization processes on the storage adapter.

namespace Zend\Cache\Storage;

interface OptimizableInterface
{
    /**
     * Optimize the storage
     *
     * [@return](https://github.com/return) bool
     */
    public function optimize();
}

The TaggableInterface

Zend\Cache\Storage\TaggableInterface implements methods for tagging items, and cleaning (expiring) items matching tags.

namespace Zend\Cache\Storage;

interface TaggableInterface
{
    /**
     * Set tags to an item by given key.
     * An empty array will remove all tags.
     *
     * [@param](https://github.com/param) string   $key
     * [@param](https://github.com/param) string[] $tags
     * [@return](https://github.com/return) bool
     */
    public function setTags($key, array $tags);

    /**
     * Get tags of an item by given key
     *
     * [@param](https://github.com/param) string $key
     * [@return](https://github.com/return) string[]|FALSE
     */
    public function getTags($key);

    /**
     * Remove items matching given tags.
     *
     * If $disjunction only one of the given tags must match
     * else all given tags must match.
     *
     * [@param](https://github.com/param) string[] $tags
     * [@param](https://github.com/param)  bool  $disjunction
     * [@return](https://github.com/return) bool
     */
    public function clearByTags(array $tags, $disjunction = false);
}

The Apc Adapter

Zend\Cache\Storage\Adapter\Apc stores cache items in shared memory through the PHP extension APC (Alternative PHP Cache).

This adapter implements the following interfaces:

• Zend\Cache\Storage\StorageInterface
• Zend\Cache\Storage\AvailableSpaceCapableInterface
• Zend\Cache\Storage\ClearByNamespaceInterface
• Zend\Cache\Storage\ClearByPrefixInterface
• Zend\Cache\Storage\FlushableInterface
• Zend\Cache\Storage\IterableInterface
• Zend\Cache\Storage\TotalSpaceCapableInterface

Capabilities

Adapter specific Options

The Dba Adapter

Zend\Cache\Storage\Adapter\Dba stores cache items into dbm-like databases using the PHP extension dba.

This adapter implements the following interfaces:

• Zend\Cache\Storage\StorageInterface
• Zend\Cache\Storage\AvailableSpaceCapableInterface
• Zend\Cache\Storage\ClearByNamespaceInterface
• Zend\Cache\Storage\ClearByPrefixInterface
• Zend\Cache\Storage\FlushableInterface
• Zend\Cache\Storage\IterableInterface
• Zend\Cache\Storage\OptimizableInterface
• Zend\Cache\Storage\TotalSpaceCapableInterface

Capabilities

Adapter specific Options

This adapter doesn't support automatic expiry

Because this adapter doesn't support automatic expiry, it's very important to clean outdated items periodically!

The Filesystem Adapter

Zend\Cache\Storage\Adapter\Filesystem stores cache items on the filesystem.

This adapter implements the following interfaces:

• Zend\Cache\Storage\StorageInterface
• Zend\Cache\Storage\AvailableSpaceCapableInterface
• Zend\Cache\Storage\ClearByNamespaceInterface
• Zend\Cache\Storage\ClearByPrefixInterface
• Zend\Cache\Storage\ClearExpiredInterface
• Zend\Cache\Storage\FlushableInterface
• Zend\Cache\Storage\IterableInterface
• Zend\Cache\Storage\OptimizableInterface
• Zend\Cache\Storage\TaggableInterface
• Zend\Cache\Storage\TotalSpaceCapableInterface

Capabilities

Adapter specific Options

Note: the suffix and tag_suffix options will be escaped in order to be safe for glob operations.

The Memcached Adapter

Zend\Cache\Storage\Adapter\Memcached stores cache items over the memcached protocol, using the PHP extension memcached, based on Libmemcached.

This adapter implements the following interfaces:

• Zend\Cache\Storage\StorageInterface
• Zend\Cache\Storage\AvailableSpaceCapableInterface
• Zend\Cache\Storage\FlushableInterface
• Zend\Cache\Storage\TotalSpaceCapableInterface

Capabilities

Adapter specific Options

The Redis Adapter

Zend\Cache\Storage\Adapter\Redis stores cache items over the redis protocol using the PHP extension redis.

This adapter implements the following interfaces:

• Zend\Cache\Storage\FlushableInterface
• Zend\Cache\Storage\TotalSpaceCapableInterface

Capabilities

Adapter specific Options

server can be described as any of the following:

• URI: /path/to/sock.sock
• Associative array: ['host' => <host>[, 'port' => <port>[, 'timeout' => <timeout>]]]
• List: [<host>[, <port>, [, <timeout>]]]

The Memory Adapter

The Zend\Cache\Storage\Adapter\Memory stores items in-memory in the current process only.

This adapter implements the following interfaces:

• Zend\Cache\Storage\StorageInterface
• Zend\Cache\Storage\AvailableSpaceCapableInterface
• Zend\Cache\Storage\ClearByPrefixInterface
• Zend\Cache\Storage\ClearExpiredInterface
• Zend\Cache\Storage\FlushableInterface
• Zend\Cache\Storage\IterableInterface
• Zend\Cache\Storage\TaggableInterface
• Zend\Cache\Storage\TotalSpaceCapableInterface

Capabilities