From abf7403620e2fb935da3987b25572c6b0fc4b702 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20B=C3=B6sing?=
 <2189546+boesing@users.noreply.github.com>
Date: Wed, 8 Apr 2020 14:46:33 +0200
Subject: [PATCH 1/3] Added `Storage\PluginAwareInterface` and
 `Storage\PluginCapableInterface`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As already mentioned in zendframework/zend-cache#177, I would like to add some more interfaces to avoid issues when implementing new adapters without the `AbstractAdapter`.

Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>
---
 src/Storage/Adapter/AbstractAdapter.php       |  26 +--
 src/Storage/PluginAwareInterface.php          |  33 +++
 src/Storage/PluginCapableInterface.php        |  30 +++
 src/StorageFactory.php                        |  22 +-
 ...erWithStorageAndEventsCapableInterface.php | 191 ++++++++++++++++++
 test/StorageFactoryTest.php                   |  18 ++
 6 files changed, 294 insertions(+), 26 deletions(-)
 create mode 100644 src/Storage/PluginAwareInterface.php
 create mode 100644 src/Storage/PluginCapableInterface.php
 create mode 100644 test/Storage/Adapter/TestAsset/AdapterWithStorageAndEventsCapableInterface.php

diff --git a/src/Storage/Adapter/AbstractAdapter.php b/src/Storage/Adapter/AbstractAdapter.php
index b3c213fb..1675a766 100644
--- a/src/Storage/Adapter/AbstractAdapter.php
+++ b/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()
     {
diff --git a/src/Storage/PluginAwareInterface.php b/src/Storage/PluginAwareInterface.php
new file mode 100644
index 00000000..9d8d3870
--- /dev/null
+++ b/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);
+}
diff --git a/src/Storage/PluginCapableInterface.php b/src/Storage/PluginCapableInterface.php
new file mode 100644
index 00000000..9f83b4ed
--- /dev/null
+++ b/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();
+}
diff --git a/src/StorageFactory.php b/src/StorageFactory.php
index 05dc8f4a..2bf3c697 100644
--- a/src/StorageFactory.php
+++ b/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.9; please use "%s" instead',
+                    EventsCapableInterface::class,
+                    PluginAwareInterface::class
+                ), E_USER_DEPRECATED);
             }
 
             if (! is_array($cfg['plugins'])) {
diff --git a/test/Storage/Adapter/TestAsset/AdapterWithStorageAndEventsCapableInterface.php b/test/Storage/Adapter/TestAsset/AdapterWithStorageAndEventsCapableInterface.php
new file mode 100644
index 00000000..4eb8b62d
--- /dev/null
+++ b/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;
+    }
+}
diff --git a/test/StorageFactoryTest.php b/test/StorageFactoryTest.php
index 632dcd80..e6321fe2 100644
--- a/test/StorageFactoryTest.php
+++ b/test/StorageFactoryTest.php
@@ -8,8 +8,11 @@
 
 namespace LaminasTest\Cache;
 
+use ErrorException;
 use Laminas\Cache;
 use Laminas\ServiceManager\ServiceManager;
+use Laminas\Stdlib\ErrorHandler;
+use LaminasTest\Cache\Storage\Adapter\TestAsset\AdapterWithStorageAndEventsCapableInterface;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -205,4 +208,19 @@ public function testFactoryWithPluginsAndOptionsArray()
             }
         }
     }
+
+    public function testWillTriggerDeprecationWarningForMissingPluginAwareInterface()
+    {
+        $adapters = $this->prophesize(Cache\Storage\AdapterPluginManager::class);
+
+        $adapters->get('Foo')->willReturn(new AdapterWithStorageAndEventsCapableInterface());
+
+        Cache\StorageFactory::setAdapterPluginManager($adapters->reveal());
+        ErrorHandler::start(E_USER_DEPRECATED);
+
+        Cache\StorageFactory::factory(['adapter' => 'Foo', 'plugins' => ['IgnoreUserAbort']]);
+
+        $stack = ErrorHandler::stop();
+        $this->assertInstanceOf(ErrorException::class, $stack);
+    }
 }

From 1d4857e3e794f9bbf50cf1f7333c4cb4edd728fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20B=C3=B6sing?=
 <2189546+boesing@users.noreply.github.com>
Date: Mon, 20 Jul 2020 22:57:54 +0200
Subject: [PATCH 2/3] Fix upcoming minor version in deprecation message
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>
---
 src/StorageFactory.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/StorageFactory.php b/src/StorageFactory.php
index 2bf3c697..6c38fbcb 100644
--- a/src/StorageFactory.php
+++ b/src/StorageFactory.php
@@ -84,7 +84,7 @@ public static function factory($cfg)
 
                 trigger_error(sprintf(
                     'Using "%s" to provide plugin capabilities to storage adapters is deprecated as of '
-                    . 'laminas-cache 2.9; please use "%s" instead',
+                    . 'laminas-cache 2.10; please use "%s" instead',
                     EventsCapableInterface::class,
                     PluginAwareInterface::class
                 ), E_USER_DEPRECATED);

From eb0361bb66dbdfd4d3cf2f3c9f6bd06bde015c44 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20B=C3=B6sing?=
 <2189546+boesing@users.noreply.github.com>
Date: Tue, 6 Oct 2020 00:27:09 +0200
Subject: [PATCH 3/3] Added CHANGELOG entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>
---
 CHANGELOG.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0fb7c4a2..50054aa3 100644
--- a/CHANGELOG.md
+++ b/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