feature #18069 [DoctrineBridge] deprecate MergeDoctrineCollectionListener::onBind() (HeahDude)

This PR was merged into the 3.1-dev branch.

Discussion
----------

[DoctrineBridge] deprecate `MergeDoctrineCollectionListener::onBind()`

| Q             | A
| ------------- | ---
| Branch        | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | -

Commits
-------

ad08b95 [DoctrineBridge] deprecated `MergeDoctrineCollectionListener::onBind()`

src/Symfony/Bridge/Doctrine/CHANGELOG.md

@@ -4,7 +4,9 @@ CHANGELOG
 3.1.0
 -----
 
- * added "{{ value }}" message placeholder to UniqueEntityValidator 
+ * added "{{ value }}" message placeholder to UniqueEntityValidator
+ * deprecated `MergeDoctrineCollectionListener::onBind` in favor of
+   `MergeDoctrineCollectionListener::onSubmit`
 
 3.0.0
 -----

src/Symfony/Bridge/Doctrine/Form/EventListener/MergeDoctrineCollectionListener.php

@@ -27,15 +27,31 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  */
 class MergeDoctrineCollectionListener implements EventSubscriberInterface
 {
+    // Keeps BC. To be removed in 4.0
+    private $bc = true;
+
     public static function getSubscribedEvents()
     {
         // Higher priority than core MergeCollectionListener so that this one
         // is called before
-        return array(FormEvents::SUBMIT => array('onBind', 10));
+        return array(
+            FormEvents::SUBMIT => array(
+                // BC
+                array('onBind', 10),
+                array('onSubmit', 5),
+            ),
+        );
     }
 
-    public function onBind(FormEvent $event)
+    public function onSubmit(FormEvent $event)
     {
+        // If onBind() is overridden then logic has been executed
+        if ($this->bc) {
+            @trigger_error('The onBind() method is deprecated since version 3.1 and will be removed in 4.0. Use the onSubmit() method instead.', E_USER_DEPRECATED);
+
+            return;
+        }
+
         $collection = $event->getForm()->getData();
         $data = $event->getData();
 
@@ -45,4 +61,17 @@ class MergeDoctrineCollectionListener implements EventSubscriberInterface
             $collection->clear();
         }
     }
+
+    /**
+     * Alias of {@link onSubmit()}.
+     *
+     * @deprecated since version 3.1, to be removed in 4.0.
+     *             Use {@link onSubmit()} instead.
+     */
+    public function onBind()
+    {
+        if (__CLASS__ === get_class($this)) {
+            $this->bc = false;
+        }
+    }
 }

src/Symfony/Bridge/Doctrine/Tests/Form/EventListener/MergeDoctrineCollectionTest.php

@@ -0,0 +1,80 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\Doctrine\Tests\Form\EventListener;
+
+use Doctrine\Common\Collections\ArrayCollection;
+use Symfony\Bridge\Doctrine\Form\EventListener\MergeDoctrineCollectionListener;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+use Symfony\Component\Form\FormBuilder;
+use Symfony\Component\Form\FormEvent;
+use Symfony\Component\Form\FormEvents;
+
+class MergeDoctrineCollectionTest extends \PHPUnit_Framework_TestCase
+{
+    /** @var \Doctrine\Common\Collections\ArrayCollection */
+    private $collection;
+    /** @var \Symfony\Component\EventDispatcher\EventDispatcher */
+    private $dispatcher;
+    private $factory;
+    private $form;
+
+    protected function setUp()
+    {
+        $this->collection = new ArrayCollection(array('test'));
+        $this->dispatcher = new EventDispatcher();
+        $this->factory = $this->getMock('Symfony\Component\Form\FormFactoryInterface');
+        $this->form = $this->getBuilder()
+            ->getForm();
+    }
+
+    protected function tearDown()
+    {
+        $this->collection = null;
+        $this->dispatcher = null;
+        $this->factory = null;
+        $this->form = null;
+    }
+
+    protected function getBuilder($name = 'name')
+    {
+        return new FormBuilder($name, null, $this->dispatcher, $this->factory);
+    }
+
+    protected function getForm($name = 'name')
+    {
+        return $this->getBuilder($name)
+            ->setData($this->collection)
+            ->addEventSubscriber(new MergeDoctrineCollectionListener())
+            ->getForm();
+    }
+
+    public function testOnSubmitDoNothing()
+    {
+        $submittedData = array('test');
+        $event = new FormEvent($this->getForm(), $submittedData);
+
+        $this->dispatcher->dispatch(FormEvents::SUBMIT, $event);
+
+        $this->assertTrue($this->collection->contains('test'));
+        $this->assertSame(1, $this->collection->count());
+    }
+
+    public function testOnSubmitNullClearCollection()
+    {
+        $submittedData = array();
+        $event = new FormEvent($this->getForm(), $submittedData);
+
+        $this->dispatcher->dispatch(FormEvents::SUBMIT, $event);
+
+        $this->assertTrue($this->collection->isEmpty());
+    }
+}