Zend\Cache\Storage\Plugin

Overview

Cache storage plugins are objects to add missing functionality or to influence behavior of a storage adapter.

The plugins listen to events the adapter triggers and can change called method arguments (*.post - events), skipping and directly return a result (using stopPropagation), changing the result (with setResult of Zend\Cache\Storage\PostEvent) and catching exceptions (with Zend\Cache\Storage\ExceptionEvent).

Quick Start

Storage plugins can either be created from Zend\Cache\StorageFactory with the pluginFactory, or by simply instantiating one of the Zend\Cache\Storage\Plugin\*classes.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
use Zend\Cache\StorageFactory;

// Via factory:
$cache = StorageFactory::factory(array(
    'adapter' => 'filesystem',
    'plugins' => array('serializer'),
));

// Alternately:
$cache  = StorageFactory::adapterFactory('filesystem');
$plugin = StorageFactory::pluginFactory('serializer');
$cache->addPlugin($plugin);

// Or manually:
$cache  = new Zend\Cache\Storage\Adapter\Filesystem();
$plugin = new Zend\Cache\Storage\Plugin\Serializer();
$cache->addPlugin($plugin);

The ClearExpiredByFactor Plugin

The Zend\Cache\Storage\Plugin\ClearExpiredByFactor plugin calls the storage method clearExpired() randomly (by factor) after every call of setItem(), setItems(), addItem() and addItems().
Plugin specific options
Name Data Type Default Value Description
clearing_factor integer 0 The automatic clearing factor

Note

** The ClearExpiredInterface is required **

The storage have to implement the Zend\Cache\Storage\ClearExpiredInterface to work with this plugin.

The ExceptionHandler Plugin

The Zend\Cache\Storage\Plugin\ExceptionHandler plugin catches all exceptions thrown on reading or writing to cache and sends the exception to a defined callback function.

It’s configurable if the plugin should re-throw the catched exception.

Plugin specific options
Name Data Type Default Value Description
exception_callback callable null null Callback will be called on an exception and get the exception as argument
throw_exceptions boolean true Re-throw catched exceptions

The IgnoreUserAbort Plugin

The Zend\Cache\Storage\Plugin\IgnoreUserAbort plugin ignores script terminations by users until write operations to cache finished.
Plugin specific options
Name Data Type Default Value Description
exit_on_abort boolean true Terminate script execution if user abort the script

The OptimizeByFactor Plugin

The Zend\Cache\Storage\Plugin\OptimizeByFactor plugin calls the storage method optimize() randomly (by factor) after removing items from cache.
Plugin specific options
Name Data Type Default Value Description
optimizing_factor integer 0 The automatic optimization factor

Note

** The OptimizableInterface is required **

The storage have to implement the Zend\Cache\Storage\OptimizableInterface to work with this plugin.

The Serializer Plugin

The Zend\Cache\Storage\Plugin\Serializer plugin will serialize data on writing to cache and unserialize on reading. So it’s possible to store different datatypes into cache storages only support strings.
Plugin specific options
Name Data Type Default Value Description
serializer null string Zend\Serializer\Adapter\AdapterInterface null

The serializer to use

  • If null use the default serializer
  • If string instantiate the serializer with serializer_options
serializer_options array [] Array of serializer options used to instantiate the serializer

Available Methods

setOptions(Zend\Cache\Storage\Plugin\PluginOptions $options)

Set options.

Return type:Zend\Cache\Storage\Plugin\PluginInterface
getOptions()

Get options.

Return type:Zend\Cache\Storage\Plugin\PluginOptions
attach(Zend\EventManager\EventManagerInterface $events)

Defined by Zend\EventManager\ListenerAggregateInterface, attach one or more listeners.

Return type:void
detach(Zend\EventManager\EventManagerInterface $events)

Defined by Zend\EventManager\ListenerAggregateInterface, detach all previously attached listeners.

Return type:void

Examples

Basics of writing an own storage plugin

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
use Zend\Cache\Storage\Event;
use Zend\Cache\Storage\Plugin\AbstractPlugin;
use Zend\EventManager\EventManagerInterface;

class MyPlugin extends AbstractPlugin
{

    protected $handles = array();

    // This method have to attach all events required by this plugin
    public function attach(EventManagerInterface $events)
    {
        $this->handles[] = $events->attach('getItem.pre', array($this, 'onGetItemPre'));
        $this->handles[] = $events->attach('getItem.post', array($this, 'onGetItemPost'));
        return $this;
    }

    // This method have to detach all events required by this plugin
    public function detach(EventManagerInterface $events)
    {
        foreach ($this->handles as $handle) {
           $events->detach($handle);
        }
        $this->handles = array();
        return $this;
    }

    public function onGetItemPre(Event $event)
    {
        $params = $event->getParams();
        echo sprintf("Method 'getItem' with key '%s' started\n", params['key']);
    }

    public function onGetItemPost(Event $event)
    {
        $params = $event->getParams();
        echo sprintf("Method 'getItem' with key '%s' finished\n", params['key']);
    }
}

// After defining this basic plugin we can instantiate and add it to an adapter instance
$plugin = new MyPlugin();
$cache->addPlugin($plugin);

// Now on calling getItem our basic plugin should print the expected output
$cache->getItem('cache-key');
// Method 'getItem' with key 'cache-key' started
// Method 'getItem' with key 'cache-key' finished