.. _zend.cache.storage.adapter: Zend\\Cache\\Storage\\Adapter ============================= .. _zend.cache.storage.adapter.intro: Overview -------- Storage adapters are wrappers for real storage resources such as memory and 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 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 operations throw an exception on error, you need to catch them manually or you can use the plug-in ``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. .. _zend.cache.storage.adapter.quick-start: 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. .. code-block:: php :linenos: 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); .. _zend.cache.storage.adapter.options: Basic Configuration Options --------------------------- .. _zend.cache.adapter.common.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`` |"zfcache" |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 | +--------------+-------------------------+----------------+-------------------------------------------------+ .. _zend.cache.storage.adapter.methods-storage-interface: The StorageInterface -------------------- The ``Zend\Cache\Storage\StorageInterface`` is the basic interface implemented by all storage adapters. .. function:: getItem(string $key, boolean & $success = null, mixed & $casToken = null) :noindex: 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``. :rtype: mixed .. function:: getItems(array $keys) :noindex: Load all items given by $keys returning key-value pairs. :rtype: array .. function:: hasItem(string $key) :noindex: Test if an item exists. :rtype: boolean .. function:: hasItems(array $keys) :noindex: Test multiple items. :rtype: string[] .. function:: getMetadata(string $key) :noindex: Get metadata of an item. :rtype: array|boolean .. function:: getMetadatas(array $keys) :noindex: Get multiple metadata. :rtype: array .. function:: setItem(string $key, mixed $value) :noindex: Store an item. :rtype: boolean .. function:: setItems(array $keyValuePairs) :noindex: Store multiple items. :rtype: boolean .. function:: addItem(string $key, mixed $value) :noindex: Add an item. :rtype: boolean .. function:: addItems(array $keyValuePairs) :noindex: Add multiple items. :rtype: boolean .. function:: replaceItem(string $key, mixed $value) :noindex: Replace an item. :rtype: boolean .. function:: replaceItems(array $keyValuePairs) :noindex: Replace multiple items. :rtype: boolean .. function:: checkAndSetItem(mixed $token, string $key, mixed $value) :noindex: Set item only if token matches. It uses the token received from ``getItem()`` to check if the item has changed before overwriting it. :rtype: boolean .. function:: touchItem(string $key) :noindex: Reset lifetime of an item. :rtype: boolean .. function:: touchItems(array $keys) :noindex: Reset lifetime of multiple items. :rtype: boolean .. function:: removeItem(string $key) :noindex: Remove an item. :rtype: boolean .. function:: removeItems(array $keys) :noindex: Remove multiple items. :rtype: boolean .. function:: incrementItem(string $key, int $value) :noindex: Increment an item. :rtype: integer|boolean .. function:: incrementItems(array $keyValuePairs) :noindex: Increment multiple items. :rtype: boolean .. function:: decrementItem(string $key, int $value) :noindex: Decrement an item. :rtype: interger|boolean .. function:: decrementItems(array $keyValuePairs) :noindex: Decrement multiple items. :rtype: boolean .. function:: getCapabilities() :noindex: Capabilities of this storage. :rtype: Zend\\Cache\\Storage\\Capabilities .. _zend.cache.storage.adapter.methods-available-space-capable-interface: The AvailableSpaceCapableInterface ---------------------------------- The ``Zend\Cache\Storage\AvailableSpaceCapableInterface`` implements a method to make it possible getting the current available space of the storage. .. function:: getAvailableSpace() :noindex: Get available space in bytes. :rtype: integer|float .. _zend.cache.storage.adapter.methods-total-space-capable-interface: The TotalSpaceCapableInterface ------------------------------ The ``Zend\Cache\Storage\TotalSpaceCapableInterface`` implements a method to make it possible getting the total space of the storage. .. function:: getTotalSpace() :noindex: Get total space in bytes. :rtype: integer|float .. _zend.cache.storage.adapter.methods-clear-by-namespace-interface: The ClearByNamespaceInterface ----------------------------- The ``Zend\Cache\Storage\ClearByNamespaceInterface`` implements a method to clear all items of a given namespace. .. function:: clearByNamespace(string $namespace) :noindex: Remove items of given namespace. :rtype: boolean .. _zend.cache.storage.adapter.methods-clear-by-prefix-interface The ClearByPrefixInterface -------------------------- The ``Zend\Cache\Storage\ClearByPrefixInterface`` implements a method to clear all items of a given prefix (within the current configured namespace). .. function:: clearByPrefix(string $prefix) :noindex: Remove items matching given prefix. :rtype: boolean .. _zend.cache.storage.adapter.methods-clear-expired-interface The ClearExpiredInterface ------------------------- The ``Zend\Cache\Storage\ClearExpiredInterface`` implements a method to clear all expired items (within the current configured namespace). .. function:: clearExpired() :noindex: Remove expired items. :rtype: boolean .. _zend.cache.storage.adapter.methods-flushable-interface The FlushableInterface ---------------------- The ``Zend\Cache\Storage\FlushableInterface`` implements a method to flush the complete storage. .. function:: flush() :noindex: Flush the whole storage. :rtype: boolean .. _zend.cache.storage.adapter.methods-iterable-interface The IterableInterface --------------------- The ``Zend\Cache\Storage\IterableInterface`` implements a method to get an iterator to iterate over items of the storage. It extends ``IteratorAggregate`` so it's possible to directly iterate over the storage using ``foreach``. .. function:: getIterator() :noindex: Get an Iterator. :rtype: Zend\\Cache\\Storage\\IteratorInterface .. _zend.cache.storage.adapter.methods-optimizable-interface The OptimizableInterface ------------------------ The ``Zend\Cache\Storage\OptimizableInterface`` implements a method to run optimization processes on the storage. .. function:: optimize() :noindex: Optimize the storage. :rtype: boolean .. _zend.cache.storage.adapter.methods-taggable-interface The TaggableInterface --------------------- The ``Zend\Cache\Storage\TaggableInterface`` implements methods to mark items with one or more tags and to clean items matching tags. .. function:: setTags(string $key, string[] $tags) :noindex: Set tags to an item by given key. (An empty array will remove all tags) :rtype: boolean .. function:: getTags(string $key) :noindex: Get tags of an item by given key. :rtype: string[]|false .. function:: clearByTags(string[] $tags, boolean $disjunction = false) :noindex: Remove items matching given tags. If $disjunction is ``true`` only one of the given tags must match else all given tags must match. :rtype: boolean .. _zend.cache.storage.adapter.apc The Apc Adapter --------------- The ``Zend\Cache\Storage\Adapter\Apc`` adapter stores cache items in shared memory through the required 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`` .. _zend.cache.storage.adapter.apc.capabilities .. table:: Capabilities +--------------------+-------------------------------------------------------------------------------------------------------------+ |Capability |Value | +====================+=============================================================================================================+ |supportedDatatypes |``null``, ``boolean``, ``integer``, ``double``, ``string``, ``array`` (serialized), ``object`` (serialized) | +--------------------+-------------------------------------------------------------------------------------------------------------+ |supportedMetadata |internal_key, atime, ctime, mtime, rtime, size, hits, ttl | +--------------------+-------------------------------------------------------------------------------------------------------------+ |minTtl |1 | +--------------------+-------------------------------------------------------------------------------------------------------------+ |maxTtl |0 | +--------------------+-------------------------------------------------------------------------------------------------------------+ |staticTtl |``true`` | +--------------------+-------------------------------------------------------------------------------------------------------------+ |ttlPrecision |1 | +--------------------+-------------------------------------------------------------------------------------------------------------+ |useRequestTime | | +--------------------+-------------------------------------------------------------------------------------------------------------+ |expiredRead |``false`` | +--------------------+-------------------------------------------------------------------------------------------------------------+ |maxKeyLength |5182 | +--------------------+-------------------------------------------------------------------------------------------------------------+ |namespaceIsPrefix |``true`` | +--------------------+-------------------------------------------------------------------------------------------------------------+ |namespaceSeparator |