Updated migration documentation and added trait for testing migrated plugin managers

Author: Matt Kynaston

doc/book/migration.md

@@ -1137,6 +1137,8 @@ class ObserverPluginManager extends AbstractPluginManager
         'log' => LogObserver::class,
     ];
 
+    protected $shareByDefault = false;
+
     public function validatePlugin($instance)
     {
         if (! $plugin instanceof ObserverInterface) {
@@ -1156,12 +1158,16 @@ To prepare this for version 3, we need to do the following:
   `factories` and `aliases`.
 - We need to implement a `validate()` method.
 - We need to update the `validatePlugin()` method to proxy to `validate()`.
+- We need to add a `$sharedByDefault` property (if `$shareByDefault` is present)
 
 Doing so, we get the following result:
 
 ```php
+namespace MyNamespace;
+
 use RuntimeException;
 use Zend\ServiceManager\AbstractPluginManager;
+use Zend\ServiceManager\Exception\InvalidServiceException;
 use Zend\ServiceManager\Factory\InvokableFactory;
 
 class ObserverPluginManager extends AbstractPluginManager
@@ -1176,14 +1182,21 @@ class ObserverPluginManager extends AbstractPluginManager
     ];
 
     protected $factories = [
-        MailObserver::class => InvokableFactory::class,
+        MailObserver::class       => InvokableFactory::class,
         LogObserver::class => InvokableFactory::class,
+        // Legacy (v2) due to alias resolution
+        'mynamespacemailobserver' => InvokableFactory::class,
+        'mynamespacelogobserver'  => InvokableFactory::class,
     ];
 
+    protected $shareByDefault = false;
+
+    protected $sharedByDefault = false;
+
     public function validate($instance)
     {
         if (! $plugin instanceof $this->instanceOf) {
-            throw new RuntimeException(sprintf(
+            throw new InvalidServiceException(sprintf(
                 'Invalid plugin "%s" created; not an instance of %s',
                 get_class($instance),
                 $this->instanceOf
@@ -1193,7 +1206,11 @@ class ObserverPluginManager extends AbstractPluginManager
 
     public function validatePlugin($instance)
     {
-        $this->validate($instance);
+        try {
+            $this->validate($instance);
+        } catch (InvalidServiceException $e) {
+            throw new RuntimeException($e->getMessage(), $e->getCode(), $e);
+        }
     }
 }
 ```
@@ -1209,16 +1226,71 @@ Things to note about the above:
 - The aliases point to the fully qualified class name (FQCN) for the service
   being generated, and these are mapped to `InvokableFactory` instances. This
   means you can also fetch your plugins by their FQCN.
+- There are also factory entries for the canonicalized FQCN of each factory,
+  which will be used in v2.
+- `validatePlugin()` continues to throw the old exception
 
 The above will now work in both version 2 and version 3.
 
+### Migration testing
+
+To test your changes, create a new `MigrationTest` case that uses the
+`CommonPluginManagerTrait`. Override the `getPluginManager()` to return an
+instance of your plugin manager and override  `getV2InvalidPluginException()`
+to return the classname of the exception your `validatePlugin()` method throws:
+
+```php
+use MyNamespace\ObserverPluginManager;
+use MyNamespace\Exception\RuntimeException;
+use PHPUnit_Framework_TestCase as TestCase;
+use Zend\ServiceManager\ServiceManager;
+use ZendTest\ServiceManager\TestAsset\V2v3PluginManager;
+
+class MigrationTest extends TestCase
+{
+    use CommonPluginManagerTrait;
+
+    protected function getPluginManager()
+    {
+        return new ObserverPluginManager(new ServiceManager());
+    }
+
+    protected function getV2InvalidPluginException()
+    {
+        return RuntimeException::class;
+    }
+}
+```
+
+This will check that:
+
+- You have set the `$instanceOf` property
+- `$shareByDefault` and `$sharedByDefault` match, if present
+- That requesting an invalid plugin throws the right exception
+- That all your aliases resolve
+
+Note that you will need to include ServiceManager's test directory in the `autoload-dev` section of your `compoer.json`
+for this test to work:
+
+```
+    "autoload-dev": {
+        "psr-4": {
+            "MyNamespaceTest\ObserverPluginManager\\": "test/",
+            "ZendTest\\ServiceManager\\": "vendor/zendframework/zend-servicemanager/test/"
+        }
+    }
+```
+
+### Post migration
+
 After you migrate to version 3, you can clean up your plugin manager:
 
 - Remove the `validatePlugin()` method.
 - If your `validate()` routine is only checking that the instance is of a single
   type, and has no other logic, you can remove that implementation as well, as
   the `AbstractPluginManager` already takes care of that when `$instanceOf` is
   defined!
+- Remove the canonicalized FQCN entry for each factory
 
 Performing these steps on the above, we get:
 

test/CommonPluginManagerTrait.php

@@ -0,0 +1,110 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\ServiceManager;
+
+use ReflectionClass;
+use ReflectionProperty;
+use Zend\ServiceManager\Exception\InvalidServiceException;
+
+/**
+ * Trait for testing plugin managers for v2-v3 compatibility
+ *
+ * To use this trait:
+ *   * implement the `getPluginManager()` method to return your plugin manager
+ *   * implement the `getV2InvalidPluginException()` method to return the class `validatePlugin()` throws under v2
+ */
+trait CommonPluginManagerTrait
+{
+    public function testInstanceOfIsSet()
+    {
+        $manager = $this->getPluginManager();
+        $reflection = new ReflectionProperty($manager, 'instanceOf');
+        $reflection->setAccessible(true);
+        $this->assertNotNull($reflection->getValue($manager), 'instanceOf property not set');
+    }
+
+    public function testShareByDefaultAndSharedByDefault()
+    {
+        $manager = $this->getPluginManager();
+        $reflection = new ReflectionClass($manager);
+        $shareByDefault = $sharedByDefault = true;
+
+        foreach ($reflection->getProperties() as $prop) {
+            if ($prop->getName() == 'shareByDefault') {
+                $prop->setAccessible(true);
+                $shareByDefault = $prop->getValue($manager);
+            }
+            if ($prop->getName() == 'sharedByDefault') {
+                $prop->setAccessible(true);
+                $sharedByDefault = $prop->getValue($manager);
+            }
+        }
+
+        $this->assertTrue(
+            $shareByDefault == $sharedByDefault,
+            'Values of shareByDefault and sharedByDefault do not match'
+        );
+    }
+
+    public function testRegisteringInvalidElementRaisesException()
+    {
+        $this->setExpectedException($this->getServiceNotFoundException());
+        $this->getPluginManager()->setService('test', $this);
+    }
+
+    public function testLoadingInvalidElementRaisesException()
+    {
+        $manager = $this->getPluginManager();
+        $manager->setInvokableClass('test', get_class($this));
+        $this->setExpectedException($this->getServiceNotFoundException());
+        $manager->get('test');
+    }
+
+    /**
+     * @dataProvider aliasProvider
+     */
+    public function testPluginAliasesResolve($alias, $expected)
+    {
+        $this->assertInstanceOf($expected, $this->getPluginManager()->get($alias), "Alias '$alias' does not resolve'");
+    }
+
+    public function aliasProvider()
+    {
+        $manager = $this->getPluginManager();
+        $reflection = new ReflectionProperty($manager, 'aliases');
+        $reflection->setAccessible(true);
+        $data = [];
+        foreach ($reflection->getValue($manager) as $alias => $expected) {
+            $data[] = [$alias, $expected];
+        }
+        return $data;
+    }
+
+    protected function getServiceNotFoundException()
+    {
+        $manager = $this->getPluginManager();
+        if (method_exists($manager, 'configure')) {
+            return InvalidServiceException::class;
+        }
+        return $this->getV2InvalidPluginException();
+    }
+
+    /**
+     * Returns the plugin manager to test
+     * @return \Zend\ServiceManager\AbstractPluginManager
+     */
+    abstract protected function getPluginManager();
+
+    /**
+     * Returns the FQCN of the exception thrown under v2 by `validatePlugin()`
+     * @return mixed
+     */
+    abstract protected function getV2InvalidPluginException();
+}

test/ExamplePluginManagerTest.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\ServiceManager;
+
+use PHPUnit_Framework_TestCase as TestCase;
+use Zend\ServiceManager\ServiceManager;
+use ZendTest\ServiceManager\TestAsset\V2v3PluginManager;
+
+/**
+ * Example test of using CommonPluginManagerTrait
+ */
+class ExamplePluginManagerTest extends TestCase
+{
+    use CommonPluginManagerTrait;
+
+    protected function getPluginManager()
+    {
+        return new V2v3PluginManager(new ServiceManager());
+    }
+
+    protected function getV2InvalidPluginException()
+    {
+        return \RuntimeException::class;
+    }
+}