vendor/zendframework/zend-cache/doc/book/storage/plugin.md

   1 # Storage Plugins
   2
   3 Cache storage plugins are objects that provide additional functionality to or
   4 influence behavior of a storage adapter.
   5
   6 The plugins listen to events the adapter triggers, and can:
   7
   8 - change the arguments provided to the method triggering the event (via `*.post` events)
   9 - skip and directly return a result (by calling `stopPropagation`)
  10 - change the result (by calling `setResult` on the provided `Zend\Cache\Storage\PostEvent`)
  11 - catch exceptions (by reacting to `Zend\Cache\Storage\ExceptionEvent`)
  12
  13 ## Quick Start
  14
  15 Storage plugins can either be created from
  16 `Zend\Cache\StorageFactory::pluginFactory()`, or by instantiating one of the
  17 `Zend\Cache\Storage\Plugin\*` classes.
  18
  19 To make life easier, `Zend\Cache\StorageFactory::factory()` can create both the
  20 requested adapter and all specified plugins at once.
  21
  22 ```php
  23 use Zend\Cache\StorageFactory;
  24
  25 // All at once:
  26 $cache = StorageFactory::factory([
  27     'adapter' => 'filesystem',
  28     'plugins' => ['serializer'],
  29 ]);
  30
  31 // Alternately, via discrete factory methods:
  32 $cache  = StorageFactory::adapterFactory('filesystem');
  33 $plugin = StorageFactory::pluginFactory('serializer');
  34 $cache->addPlugin($plugin);
  35
  36 // Or manually:
  37 $cache  = new Zend\Cache\Storage\Adapter\Filesystem();
  38 $plugin = new Zend\Cache\Storage\Plugin\Serializer();
  39 $cache->addPlugin($plugin);
  40 ```
  41
  42 ## The ClearExpiredByFactor Plugin
  43
  44 `Zend\Cache\Storage\Plugin\ClearExpiredByFactor` calls the storage method
  45 `clearExpired()` randomly (by factor) after every call of `setItem()`,
  46 `setItems()`, `addItem()`, and `addItems()`.
  47
  48 ### Plugin specific options
  49
  50 Name | Data Type | Default Value | Description
  51 ---- | --------- | ------------- | -----------
  52 `clearing_factor` | `integer` | `0` | The automatic clearing factor.
  53
  54 > ### Adapter must implement ClearExpiredInterface
  55 >
  56 > The storage adapter must implement `Zend\Cache\Storage\ClearExpiredInterface`
  57 > to work with this plugin.
  58
  59 ## The ExceptionHandler Plugin
  60
  61 `Zend\Cache\Storage\Plugin\ExceptionHandler` catches all exceptions thrown on
  62 reading from or writing to the cache, and sends the exception to a defined callback function.
  63 You may also configure the plugin to re-throw exceptions.
  64
  65 ### Plugin specific options
  66
  67 Name | Data Type | Default Value | Description
  68 ---- | --------- | ------------- | -----------
  69 `exception_callback` | `callable|null` | null | Callback to invoke on exception; receives the exception as the sole argument.
  70 `throw_exceptions` | `boolean` | `true` | Re-throw caught exceptions.
  71
  72 ## The IgnoreUserAbort Plugin
  73
  74 `Zend\Cache\Storage\Plugin\IgnoreUserAbort` ignores user-invoked script
  75 termination when, allowing cache write operations to complete first.
  76
  77 ### Plugin specific options
  78
  79 Name | Data Type | Default Value | Description
  80 ---- | --------- | ------------- | -----------
  81 `exit_on_abort` | `boolean` | `true` | Terminate script execution on user abort.
  82
  83 ## The OptimizeByFactor Plugin
  84
  85 `Zend\Cache\Storage\Plugin\OptimizeByFactor` calls the storage method `optimize()`
  86 randomly (by factor) after removing items from the cache.
  87
  88 ### Plugin specific options
  89
  90 Name | Data Type | Default Value | Description
  91 ---- | --------- | ------------- | -----------
  92 `optimizing_factor` | `integer` | `0` | The automatic optimization factor.
  93
  94 > ### Adapter must implement OptimizableInterface
  95 >
  96 > The storage adapter must implement `Zend\Cache\Storage\OptimizableInterface`
  97 > to work with this plugin.
  98
  99 ## The Serializer Plugin
 100
 101 `Zend\Cache\Storage\Plugin\Serializer` will serialize data when writing to
 102 cache, and deserialize when reading. This allows storing datatypes not supported
 103 by the underlying storage adapter.
 104
 105 ### Plugin specific options
 106
 107 Name | Data Type | Default Value | Description
 108 ---- | --------- | ------------- | -----------
 109 `serializer` | `null|string|Zend\Serializer\Adapter\AdapterInterface` | `null` | The serializer to use; see below.
 110 `serializer_options` | `array` | `[]` | Array of options to use when instantiating the specified serializer.
 111
 112 The `serializer` value has two special cases:
 113
 114 - When `null`, the default serializer is used (JSON).
 115 - When a `string`, the value will be pulled via
 116   `Zend\Serializer\AdapterPluginManager`, with the provided
 117   `serializer_options`.
 118
 119 ## Available Methods
 120
 121 The following methods are available to all `Zend\Cache\Storage\Plugin\PluginInterface` implementations:
 122
 123 ```php
 124 namespace Zend\Cache\Storage\Plugin;
 125
 126 use Zend\EventManager\EventManagerInterface;
 127 use Zend\EventManager\ListenerAggregateInterface;
 128
 129 interface PluginInterface extends ListenerAggregateInterface
 130 {
 131     /**
 132      * Set options
 133      *
 134      * @param  PluginOptions $options
 135      * @return PluginInterface
 136      */
 137     public function setOptions(PluginOptions $options);
 138
 139     /**
 140      * Get options
 141      *
 142      * @return PluginOptions
 143      */
 144     public function getOptions();
 145
 146     /**
 147      * Attach listeners; inherited from ListenerAggregateInterface.
 148      *
 149      * @param EventManagerInterface $events
 150      * @return void
 151      */
 152     public function attach(EventManagerInterface $events);
 153
 154     /**
 155      * Detach listeners; inherited from ListenerAggregateInterface.
 156      *
 157      * @param EventManagerInterface $events
 158      * @return void
 159      */
 160     public function attach(EventManagerInterface $events);
 161 }
 162 ```
 163
 164 ## Examples
 165
 166 ### Basic plugin implementation
 167
 168 ```php
 169 use Zend\Cache\Storage\Event;
 170 use Zend\Cache\Storage\Plugin\AbstractPlugin;
 171 use Zend\EventManager\EventManagerInterface;
 172
 173 class MyPlugin extends AbstractPlugin
 174 {
 175     protected $handles = [];
 176
 177     /**
 178      * Attach to all events this plugin is interested in.
 179      */
 180     public function attach(EventManagerInterface $events)
 181     {
 182         $this->handles[] = $events->attach('getItem.pre', array($this, 'onGetItemPre'));
 183         $this->handles[] = $events->attach('getItem.post', array($this, 'onGetItemPost'));
 184     }
 185
 186     /**
 187      * Detach all handlers this plugin previously attached.
 188      */
 189     public function detach(EventManagerInterface $events)
 190     {
 191         foreach ($this->handles as $handle) {
 192            $events->detach($handle);
 193         }
 194         $this->handles = [];
 195     }
 196
 197     public function onGetItemPre(Event $event)
 198     {
 199         $params = $event->getParams();
 200         echo sprintf("Method 'getItem' with key '%s' started\n", $params['key']);
 201     }
 202
 203     public function onGetItemPost(Event $event)
 204     {
 205         $params = $event->getParams();
 206         echo sprintf("Method 'getItem' with key '%s' finished\n", $params['key']);
 207     }
 208 }
 209
 210 // After defining this plugin, we can instantiate and add it to an adapter
 211 // instance:
 212 $plugin = new MyPlugin();
 213 $cache->addPlugin($plugin);
 214
 215 // Now when calling getItem(), our plugin should print the expected output:
 216 $cache->getItem('cache-key');
 217 // Method 'getItem' with key 'cache-key' started
 218 // Method 'getItem' with key 'cache-key' finished
 219 ```