Added plugin interfaces and marked EventsCapableInterface as deprecated

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Added
 
+- [#21](https://github.com/laminas/laminas-cache/pull/21) Adds new `PluginAwareInterface` and `PluginCapableInterface` to provide better typehinting against plugin capable storage adapters
 - [#40](https://github.com/laminas/laminas-cache/pull/40) Adds installation instructions to documentation.
 
 ### Changed
@@ -14,7 +15,7 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Deprecated
 
-- Nothing.
+- [#21](https://github.com/laminas/laminas-cache/pull/21) In case the `StorageFactory` has to create a custom `StorageAdapterInterface` implementation which does not extend the `AbstractAdapter`, the factory will trigger a deprecation message due to the missing `PluginAwareInterface` implementation when a `plugins` configuration was provided.
 
 ### Removed
 

src/Storage/Adapter/AbstractAdapter.php

@@ -14,16 +14,16 @@
 use Laminas\Cache\Storage\Event;
 use Laminas\Cache\Storage\ExceptionEvent;
 use Laminas\Cache\Storage\Plugin;
+use Laminas\Cache\Storage\PluginAwareInterface;
 use Laminas\Cache\Storage\PostEvent;
 use Laminas\Cache\Storage\StorageInterface;
 use Laminas\EventManager\EventManager;
 use Laminas\EventManager\EventManagerInterface;
-use Laminas\EventManager\EventsCapableInterface;
 use SplObjectStorage;
 use stdClass;
 use Traversable;
 
-abstract class AbstractAdapter implements StorageInterface, EventsCapableInterface
+abstract class AbstractAdapter implements StorageInterface, PluginAwareInterface
 {
     /**
      * The used EventManager if any
@@ -252,10 +252,7 @@ protected function triggerException($eventName, ArrayObject $args, & $result, \E
     }
 
     /**
-     * Check if a plugin is registered
-     *
-     * @param  Plugin\PluginInterface $plugin
-     * @return bool
+     * {@inheritdoc}
      */
     public function hasPlugin(Plugin\PluginInterface $plugin)
     {
@@ -264,12 +261,7 @@ public function hasPlugin(Plugin\PluginInterface $plugin)
     }
 
     /**
-     * Register a plugin
-     *
-     * @param  Plugin\PluginInterface $plugin
-     * @param  int $priority
-     * @return AbstractAdapter Provides a fluent interface
-     * @throws Exception\LogicException
+     * {@inheritdoc}
      */
     public function addPlugin(Plugin\PluginInterface $plugin, $priority = 1)
     {
@@ -288,11 +280,7 @@ public function addPlugin(Plugin\PluginInterface $plugin, $priority = 1)
     }
 
     /**
-     * Unregister an already registered plugin
-     *
-     * @param  Plugin\PluginInterface $plugin
-     * @return AbstractAdapter Provides a fluent interface
-     * @throws Exception\LogicException
+     * {@inheritdoc}
      */
     public function removePlugin(Plugin\PluginInterface $plugin)
     {
@@ -305,9 +293,7 @@ public function removePlugin(Plugin\PluginInterface $plugin)
     }
 
     /**
-     * Return registry of plugins
-     *
-     * @return SplObjectStorage
+     * {@inheritdoc}
      */
     public function getPluginRegistry()
     {

src/Storage/PluginAwareInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * @see       https://github.com/laminas/laminas-cache for the canonical source repository
+ * @copyright https://github.com/laminas/laminas-cache/blob/master/COPYRIGHT.md
+ * @license   https://github.com/laminas/laminas-cache/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Laminas\Cache\Storage;
+
+use Laminas\Cache\Exception;
+
+interface PluginAwareInterface extends PluginCapableInterface
+{
+    /**
+     * Register a plugin
+     *
+     * @param  Plugin\PluginInterface $plugin
+     * @param  int $priority
+     * @return StorageInterface
+     * @throws Exception\LogicException
+     */
+    public function addPlugin(Plugin\PluginInterface $plugin, $priority = 1);
+
+    /**
+     * Unregister an already registered plugin
+     *
+     * @param  Plugin\PluginInterface $plugin
+     * @return StorageInterface
+     * @throws Exception\LogicException
+     */
+    public function removePlugin(Plugin\PluginInterface $plugin);
+}

src/Storage/PluginCapableInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * @see       https://github.com/laminas/laminas-cache for the canonical source repository
+ * @copyright https://github.com/laminas/laminas-cache/blob/master/COPYRIGHT.md
+ * @license   https://github.com/laminas/laminas-cache/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Laminas\Cache\Storage;
+
+use Laminas\EventManager\EventsCapableInterface;
+use SplObjectStorage;
+
+interface PluginCapableInterface extends EventsCapableInterface
+{
+    /**
+     * Check if a plugin is registered
+     *
+     * @param  Plugin\PluginInterface $plugin
+     * @return bool
+     */
+    public function hasPlugin(Plugin\PluginInterface $plugin);
+
+    /**
+     * Return registry of plugins
+     *
+     * @return SplObjectStorage
+     */
+    public function getPluginRegistry();
+}

src/StorageFactory.php

@@ -8,6 +8,7 @@
 
 namespace Laminas\Cache;
 
+use Laminas\Cache\Storage\PluginAwareInterface;
 use Laminas\EventManager\EventsCapableInterface;
 use Laminas\ServiceManager\ServiceManager;
 use Laminas\Stdlib\ArrayUtils;
@@ -72,12 +73,21 @@ public static function factory($cfg)
 
         // add plugins
         if (isset($cfg['plugins'])) {
-            if (! $adapter instanceof EventsCapableInterface) {
-                throw new Exception\RuntimeException(sprintf(
-                    "The adapter '%s' doesn't implement '%s' and therefore can't handle plugins",
-                    get_class($adapter),
-                    'Laminas\EventManager\EventsCapableInterface'
-                ));
+            if (! $adapter instanceof PluginAwareInterface) {
+                if (! $adapter instanceof EventsCapableInterface) {
+                    throw new Exception\RuntimeException(sprintf(
+                        "The adapter '%s' doesn't implement '%s' and therefore can't handle plugins",
+                        get_class($adapter),
+                        EventsCapableInterface::class
+                    ));
+                }
+
+                trigger_error(sprintf(
+                    'Using "%s" to provide plugin capabilities to storage adapters is deprecated as of '
+                    . 'laminas-cache 2.10; please use "%s" instead',
+                    EventsCapableInterface::class,
+                    PluginAwareInterface::class
+                ), E_USER_DEPRECATED);
             }
 
             if (! is_array($cfg['plugins'])) {

test/Storage/Adapter/TestAsset/AdapterWithStorageAndEventsCapableInterface.php

@@ -0,0 +1,191 @@
+<?php
+
+namespace LaminasTest\Cache\Storage\Adapter\TestAsset;
+
+use Laminas\Cache\Storage\Plugin\PluginInterface;
+use Laminas\Cache\Storage\StorageInterface;
+use Laminas\EventManager\EventsCapableInterface;
+
+final class AdapterWithStorageAndEventsCapableInterface implements StorageInterface, EventsCapableInterface
+{
+
+    /**
+     * @inheritDoc
+     */
+    public function getEventManager()
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setOptions($options)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOptions()
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getItem($key, &$success = null, &$casToken = null)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getItems(array $keys)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasItem($key)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasItems(array $keys)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getMetadata($key)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getMetadatas(array $keys)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setItem($key, $value)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setItems(array $keyValuePairs)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addItem($key, $value)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addItems(array $keyValuePairs)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function replaceItem($key, $value)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function replaceItems(array $keyValuePairs)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function checkAndSetItem($token, $key, $value)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function touchItem($key)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function touchItems(array $keys)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function removeItem($key)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function removeItems(array $keys)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function incrementItem($key, $value)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function incrementItems(array $keyValuePairs)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function decrementItem($key, $value)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function decrementItems(array $keyValuePairs)
+    {
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getCapabilities()
+    {
+    }
+
+    public function hasPlugin(PluginInterface $plugin)
+    {
+        return true;
+    }
+}