Merge pull request #1997 from emulienfou/listener-event-subscriber

Change `ResolveTargetDocumentListener` to be an event subscriber instead of an event listener

Author: alcaeus

UPGRADE-1.3.md

@@ -1,5 +1,31 @@
 # UPGRADE FROM 1.2 TO 1.3
 
+## Events
+
+### `onClassMetadataNotFound` event added
+
+The default ClassMetadataFactory now triggers an `onClassMetadataNotFound` event
+when no metadata was found for a given class. The event args contain information
+about the loaded class and can store a metadata object which can be used to load
+custom metadata when none was found.
+
+### `ResolveTargetDocumentListener` is now an event subscriber
+
+The `Doctrine\ODM\MongoDB\Tools\ResolveTargetDocumentListener` class now
+implements the `EventSubscriber` interface. You can still register it as a
+listener as was necessary previously, but in order to use new functionality you
+have to register it as an event subscriber.
+
+### `ResolveTargetDocumentListener` resolves class names on document load
+
+The `Doctrine\ODM\MongoDB\Tools\ResolveTargetDocumentListener` class not only
+resolves class names when looking up the `targetDoccumet` of an association in
+a document, but it also uses the new `onClassMetadataNotFound` event to resolve
+class names and trigger a secondary metadata load cycle if no metadata was found
+for the original class name. To use this functionality, either register an event
+listener for the `onClassMetadataNotFound` event or register the entire class as
+an event subscriber.
+
 ## GridFS
 
 GridFS support will be rewritten for 2.0 and was deprecated in its current form.

docs/en/cookbook/resolve-target-document-listener.rst

@@ -10,7 +10,8 @@ Doctrine MongoDB ODM includes a utility called
 inside Doctrine and rewriting ``targetDocument`` parameters in your metadata
 mapping at runtime. This allows your bundle to use an interface or abstract
 class in its mappings while still allowing the mapping to resolve to a concrete
-document class at runtime.
+document class at runtime. It will also rewrite class names when no mapping
+metadata has been found for the original class name.
 
 This functionality allows you to define relationships between different
 documents without creating hard dependencies.
@@ -126,7 +127,7 @@ you cannot be guaranteed that the targetDocument resolution will occur reliably:
     );
 
     // Add the ResolveTargetDocumentListener
-    $evm->addEventListener(\Doctrine\ODM\MongoDB\Events::loadClassMetadata, $rtdl);
+    $evm->addEventSubscriber($rtdl);
 
     // Create the document manager as you normally would
     $dm = \Doctrine\ODM\MongoDB\DocumentManager::create($connectionOptions, $config, $evm);

lib/Doctrine/ODM/MongoDB/Tools/ResolveTargetDocumentListener.php

@@ -2,21 +2,35 @@
 
 namespace Doctrine\ODM\MongoDB\Tools;
 
+use Doctrine\Common\EventSubscriber;
 use Doctrine\ODM\MongoDB\Event\LoadClassMetadataEventArgs;
+use Doctrine\ODM\MongoDB\Event\OnClassMetadataNotFoundEventArgs;
+use Doctrine\ODM\MongoDB\Events;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
 
 /**
  * ResolveTargetDocumentListener
  *
  * Mechanism to overwrite document interfaces or classes specified as association targets.
  */
-class ResolveTargetDocumentListener
+class ResolveTargetDocumentListener implements EventSubscriber
 {
     /**
      * @var array
      */
     private $resolveTargetDocuments = array();
 
+    /**
+     * {@inheritDoc}
+     */
+    public function getSubscribedEvents()
+    {
+        return [
+            Events::loadClassMetadata,
+            Events::onClassMetadataNotFound,
+        ];
+    }
+
     /**
      * Add a target-document class name to resolve to a new class name.
      *
@@ -31,6 +45,26 @@ public function addResolveTargetDocument($originalDocument, $newDocument, array
         $this->resolveTargetDocuments[ltrim($originalDocument, "\\")] = $mapping;
     }
 
+    /**
+     * @param OnClassMetadataNotFoundEventArgs $args
+     *
+     * @internal this is an event callback, and should not be called directly
+     *
+     * @return void
+     */
+    public function onClassMetadataNotFound(OnClassMetadataNotFoundEventArgs $args)
+    {
+        if (! array_key_exists($args->getClassName(), $this->resolveTargetDocuments)) {
+            return;
+        }
+
+        $args->setFoundMetadata(
+            $args
+                ->getObjectManager()
+                ->getClassMetadata($this->resolveTargetDocuments[$args->getClassName()]['targetDocument'])
+        );
+    }
+
     /**
      * Process event and resolve new target document names.
      *

tests/Doctrine/ODM/MongoDB/Tests/Tools/ResolveTargetDocumentListenerTest.php

@@ -3,8 +3,9 @@
 namespace Doctrine\ODM\MongoDB\Tests\Tools;
 
 use Doctrine\ODM\MongoDB\Events;
-use Doctrine\ODM\MongoDB\Tools\ResolveTargetDocumentListener;
 use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
+use Doctrine\ODM\MongoDB\Mapping\ClassMetadataFactory;
+use Doctrine\ODM\MongoDB\Tools\ResolveTargetDocumentListener;
 
 class ResolveTargetDocumentListenerTest extends \Doctrine\ODM\MongoDB\Tests\BaseTest
 {
@@ -18,11 +19,17 @@ class ResolveTargetDocumentListenerTest extends \Doctrine\ODM\MongoDB\Tests\Base
      */
     protected $listener;
 
+    /**
+     * @var ClassMetadataFactory
+     */
+    private $factory;
+
     public function setUp()
     {
         parent::setUp();
 
          $this->listener = new ResolveTargetDocumentListener();
+        $this->factory = $this->dm->getMetadataFactory();
     }
 
     public function testResolveTargetDocumentListenerCanResolveTargetDocument()
@@ -51,6 +58,28 @@ public function testResolveTargetDocumentListenerCanResolveTargetDocument()
         $this->assertSame('Doctrine\ODM\MongoDB\Tests\Tools\ResolveTargetDocument', $meta['embedOne']['targetDocument']);
         $this->assertSame('Doctrine\ODM\MongoDB\Tests\Tools\TargetDocument', $meta['embedMany']['targetDocument']);
     }
+
+    public function testResolveTargetDocumentListenerCanRetrieveTargetDocumentByInterfaceName()
+    {
+        $this->listener->addResolveTargetDocument(ResolveTargetInterface::class, ResolveTargetDocument::class, []);
+
+        $this->dm->getEventManager()->addEventSubscriber($this->listener);
+
+        $cm = $this->factory->getMetadataFor(ResolveTargetInterface::class);
+
+        $this->assertSame($this->factory->getMetadataFor(ResolveTargetDocument::class), $cm);
+    }
+
+    public function testResolveTargetDocumentListenerCanRetrieveTargetDocumentByAbstractClassName()
+    {
+        $this->listener->addResolveTargetDocument(AbstractResolveTarget::class, ResolveTargetDocument::class, []);
+
+        $this->dm->getEventManager()->addEventSubscriber($this->listener);
+
+        $cm = $this->factory->getMetadataFor(AbstractResolveTarget::class);
+
+        $this->assertSame($this->factory->getMetadataFor(ResolveTargetDocument::class), $cm);
+    }
 }
 
 interface ResolveTargetInterface
@@ -62,10 +91,15 @@ interface TargetInterface extends ResolveTargetInterface
 {
 }
 
+abstract class AbstractResolveTarget implements ResolveTargetInterface
+{
+
+}
+
 /**
  * @ODM\Document
  */
-class ResolveTargetDocument implements ResolveTargetInterface
+class ResolveTargetDocument extends AbstractResolveTarget implements ResolveTargetInterface
 {
     /**
      * @ODM\Id