Merge branch '4.4'

* 4.4:
  fix the event dispatcher signature

Author: javiereguiluz

components/event_dispatcher.rst

@@ -291,8 +291,8 @@ Dispatch the Event
 
 The :method:`Symfony\\Component\\EventDispatcher\\EventDispatcher::dispatch`
 method notifies all listeners of the given event. It takes two arguments:
-the name of the event to dispatch and the ``Event`` instance to pass to
-each listener of that event::
+the ``Event`` instance to pass to each listener of that event and the name
+of the event to dispatch and ::
 
     use Acme\Store\Event\OrderPlacedEvent;
     use Acme\Store\Order;
@@ -303,7 +303,7 @@ each listener of that event::
 
     // creates the OrderPlacedEvent and dispatches it
     $event = new OrderPlacedEvent($order);
-    $dispatcher->dispatch(OrderPlacedEvent::NAME, $event);
+    $dispatcher->dispatch($event, OrderPlacedEvent::NAME);
 
 Notice that the special ``OrderPlacedEvent`` object is created and passed to
 the ``dispatch()`` method. Now, any listener to the ``order.placed``
@@ -423,7 +423,7 @@ It is possible to detect if an event was stopped by using the
 method which returns a boolean value::
 
     // ...
-    $dispatcher->dispatch('foo.event', $event);
+    $dispatcher->dispatch($event, 'foo.event');
     if ($event->isPropagationStopped()) {
         // ...
     }
@@ -441,36 +441,6 @@ name and a reference to itself to the listeners. This can lead to some advanced
 applications of the ``EventDispatcher`` including dispatching other events inside
 listeners, chaining events or even lazy loading listeners into the dispatcher object.
 
-.. index::
-   single: EventDispatcher; Dispatcher shortcuts
-
-.. _event_dispatcher-shortcuts:
-
-Dispatcher Shortcuts
-~~~~~~~~~~~~~~~~~~~~
-
-If you do not need a custom event object, you can rely on a plain
-:class:`Symfony\\Contracts\\EventDispatcher\\Event` object. You do not even
-need to pass this to the dispatcher as it will create one by default unless you
-specifically pass one::
-
-    $dispatcher->dispatch('order.placed');
-
-Moreover, the event dispatcher always returns whichever event object that
-was dispatched, i.e. either the event that was passed or the event that
-was created internally by the dispatcher. This allows for nice shortcuts::
-
-    if (!$dispatcher->dispatch('foo.event')->isPropagationStopped()) {
-        // ...
-    }
-
-Or::
-
-    $event = new OrderPlacedEvent($order);
-    $order = $dispatcher->dispatch('bar.event', $event)->getOrder();
-
-and so on.
-
 .. index::
    single: EventDispatcher; Event name introspection
 

components/event_dispatcher/generic_event.rst

@@ -53,7 +53,7 @@ Passing a subject::
     use Symfony\Component\EventDispatcher\GenericEvent;
 
     $event = new GenericEvent($subject);
-    $dispatcher->dispatch('foo', $event);
+    $dispatcher->dispatch($event, 'foo');
 
     class FooListener
     {
@@ -74,7 +74,7 @@ access the event arguments::
         $subject,
         ['type' => 'foo', 'counter' => 0]
     );
-    $dispatcher->dispatch('foo', $event);
+    $dispatcher->dispatch($event, 'foo');
 
     class FooListener
     {
@@ -93,7 +93,7 @@ Filtering data::
     use Symfony\Component\EventDispatcher\GenericEvent;
 
     $event = new GenericEvent($subject, ['data' => 'Foo']);
-    $dispatcher->dispatch('foo', $event);
+    $dispatcher->dispatch($event, 'foo');
 
     class FooListener
     {

components/event_dispatcher/traceable_dispatcher.rst

@@ -38,7 +38,7 @@ to register event listeners and dispatch events::
 
     // dispatches an event
     $event = ...;
-    $traceableEventDispatcher->dispatch('event.the_name', $event);
+    $traceableEventDispatcher->dispatch($event, 'event.the_name');
 
 After your application has been processed, you can use the
 :method:`Symfony\\Component\\EventDispatcher\\Debug\\TraceableEventDispatcherInterface::getCalledListeners`

create_framework/event_dispatcher.rst

@@ -76,7 +76,7 @@ the Response instance::
             }
 
             // dispatch a response event
-            $this->dispatcher->dispatch('response', new ResponseEvent($response, $request));
+            $this->dispatcher->dispatch(new ResponseEvent($response, $request), 'response');
 
             return $response;
         }
@@ -88,9 +88,9 @@ now dispatched::
     // example.com/src/Simplex/ResponseEvent.php
     namespace Simplex;
 
-    use Symfony\Component\EventDispatcher\Event;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Contracts\EventDispatcher\Event;
 
     class ResponseEvent extends Event
     {

event_dispatcher/method_behavior.rst

@@ -19,7 +19,7 @@ method::
         {
             // dispatch an event before the method
             $event = new BeforeSendMailEvent($subject, $message);
-            $this->dispatcher->dispatch('mailer.pre_send', $event);
+            $this->dispatcher->dispatch($event, 'mailer.pre_send');
 
             // get $foo and $bar from the event, they may have been modified
             $subject = $event->getSubject();
@@ -30,7 +30,7 @@ method::
 
             // do something after the method
             $event = new AfterSendMailEvent($returnValue);
-            $this->dispatcher->dispatch('mailer.post_send', $event);
+            $this->dispatcher->dispatch($event, 'mailer.post_send');
 
             return $event->getReturnValue();
         }