merged branch drak/fluid_eventdispatcher (PR #3546)

Commits
-------

ca70a35 [FrameworkBundle] Return Event
876cf96 [EventDispatcher] Add fluid interface on dispatch()

Discussion
----------

[2.1][EventDispatcher] Add fluid interface on dispatch()

Bug fix: no
Feature addition: yes
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: -
Todo: -

This patch allows for code like the following:-

    $response = $dispatcher->dispatch('foo', new FooEvent())->getResponse();

and

    if ($dispatcher->dispatch('foo')->isStoppedPropagation()) {
        // ...
    }

CHANGELOG-2.1.md

@@ -182,6 +182,7 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
 
  * added a reference to the EventDispatcher on the Event
  * added a reference to the Event name on the event
+ * added fluid interface to the dispatch() method which now returns the Event object
 
 ### Filesystem
 

src/Symfony/Bundle/FrameworkBundle/ContainerAwareEventDispatcher.php

@@ -164,7 +164,7 @@ class ContainerAwareEventDispatcher extends EventDispatcher
     {
         $this->lazyLoad($eventName);
 
-        parent::dispatch($eventName, $event);
+        return parent::dispatch($eventName, $event);
     }
 
     public function getContainer()

src/Symfony/Bundle/FrameworkBundle/Debug/TraceableEventDispatcher.php

@@ -47,6 +47,9 @@ class TraceableEventDispatcher extends ContainerAwareEventDispatcher implements
         $this->called = array();
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function dispatch($eventName, Event $event = null)
     {
         switch ($eventName) {
@@ -87,6 +90,8 @@ class TraceableEventDispatcher extends ContainerAwareEventDispatcher implements
                 $this->updateProfile($token);
                 break;
         }
+
+        return $event;
     }
 
     /**

src/Symfony/Component/EventDispatcher/EventDispatcher.php

@@ -39,10 +39,6 @@ class EventDispatcher implements EventDispatcherInterface
      */
     public function dispatch($eventName, Event $event = null)
     {
-        if (!isset($this->listeners[$eventName])) {
-            return;
-        }
-
         if (null === $event) {
             $event = new Event();
         }
@@ -50,7 +46,13 @@ class EventDispatcher implements EventDispatcherInterface
         $event->setDispatcher($this);
         $event->setName($eventName);
 
+        if (!isset($this->listeners[$eventName])) {
+            return $event;
+        }
+
         $this->doDispatch($this->getListeners($eventName), $eventName, $event);
+
+        return $event;
     }
 
     /**

src/Symfony/Component/EventDispatcher/EventDispatcherInterface.php

@@ -31,6 +31,8 @@ interface EventDispatcherInterface
      * @param Event  $event     The event to pass to the event handlers/listeners.
      *                          If not supplied, an empty Event instance is created.
      *
+     * @return Event
+     * 
      * @api
      */
     function dispatch($eventName, Event $event = null);

tests/Symfony/Tests/Component/EventDispatcher/EventDispatcherTest.php

@@ -110,9 +110,12 @@ class EventDispatcherTest extends \PHPUnit_Framework_TestCase
         $this->dispatcher->dispatch(self::preFoo);
         $this->assertTrue($this->listener->preFooInvoked);
         $this->assertFalse($this->listener->postFooInvoked);
+        $this->assertInstanceOf('Symfony\Component\EventDispatcher\Event', $this->dispatcher->dispatch('noevent'));
+        $this->assertInstanceOf('Symfony\Component\EventDispatcher\Event', $this->dispatcher->dispatch(self::preFoo));
         $event = new Event();
-        $this->dispatcher->dispatch(self::preFoo, $event);
+        $return = $this->dispatcher->dispatch(self::preFoo, $event);
         $this->assertEquals('pre.foo', $event->getName());
+        $this->assertSame($event, $return);
     }
 
     public function testDispatchForClosure()