Provide migration path for validatePlugin

This patch modifies `AbstractPluginManager::validate()` to check for the
existence of a `validatePlugin()` method. If found, it will:

- Trigger an `E_USER_DEPRECATED` warning indicating that
  `validatePlugin()` is deprecated.
- Call `validatePlugin()` and return.

This provides a migration path from v2 plugin managers to v3. v2 plugin
managers can continue defining validatePlugin(), but can avoid the
warning on upgrade by one of the following paths:

- Defining a `validate()` method prior to upgrade with the logic for
  validating a plugin instance, and modifying the `validatePlugin()`
  method to proxy to the new method.
- After upgrade, renaming the `validatePlugin()` method to `validate()`.
- After upgrade, removing the `validatePlugin()` method and defining the
  `$instanceOf` property to indicate the valid instance type (if only
  one is possible).

Author: weierophinney

src/AbstractPluginManager.php

@@ -128,6 +128,15 @@ public function get($name, array $options = null)
      */
     public function validate($instance)
     {
+        if (method_exists($this, 'validatePlugin')) {
+            trigger_error(sprintf(
+                '%s::validatePlugin() has been deprecated as of 3.0; please define validate() instead',
+                get_class($this)
+            ), E_USER_DEPRECATED);
+            $this->validatePlugin($instance);
+            return;
+        }
+
         if (empty($this->instanceOf) || $instance instanceof $this->instanceOf) {
             return;
         }

test/AbstractPluginManagerTest.php

@@ -306,4 +306,31 @@ public function testPluginManagersMayOptOutOfSupportingAutoInvokableServices()
         $this->setExpectedException(ServiceNotFoundException::class, TestAsset\NonAutoInvokablePluginManager::class);
         $pluginManager->get(TestAsset\InvokableObject::class);
     }
+
+    /**
+     * @group migration
+     */
+    public function testValidateWillFallBackToValidatePluginWhenDefinedAndEmitDeprecationNotice()
+    {
+        $assertionCalled = false;
+        $instance = (object) [];
+        $assertion = function ($plugin) use ($instance, &$assertionCalled) {
+            $this->assertSame($instance, $plugin);
+            $assertionCalled = true;
+        };
+        $pluginManager = new TestAsset\V2ValidationPluginManager(new ServiceManager());
+        $pluginManager->assertion = $assertion;
+
+        $errorHandlerCalled = false;
+        set_error_handler(function ($errno, $errmsg) use (&$errorHandlerCalled) {
+            $this->assertEquals(E_USER_DEPRECATED, $errno);
+            $this->assertContains('3.0', $errmsg);
+            $errorHandlerCalled = true;
+        }, E_USER_DEPRECATED);
+        $pluginManager->validate($instance);
+        restore_error_handler();
+
+        $this->assertTrue($assertionCalled, 'Assertion was not called by validatePlugin!');
+        $this->assertTrue($errorHandlerCalled, 'Error handler was not triggered by validatePlugin!');
+    }
 }

test/TestAsset/V2ValidationPluginManager.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\ServiceManager\TestAsset;
+
+use RuntimeException;
+use Zend\ServiceManager\AbstractPluginManager;
+
+class V2ValidationPluginManager extends AbstractPluginManager
+{
+    public $assertion;
+
+    public function validatePlugin($plugin)
+    {
+        if (! is_callable($this->assertion)) {
+            throw new RuntimeException(sprintf(
+                '%s requires a callable $assertion property; not currently set',
+                __CLASS__
+            ));
+        }
+
+        call_user_func($this->assertion, $plugin);
+    }
+}