Skip to content

[WCM] Update documentation for EventDispatcherAwareEvent documentation. #2476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

[WCM] Update documentation for EventDispatcherAwareEvent documentation. #2476

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0831e4f
Update documentation for EventDispatcherAwareEvent documentation.
Apr 6, 2013
7bed1cc
Wrap line
Apr 6, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 17 additions & 10 deletions components/event_dispatcher/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,11 +442,18 @@ EventDispatcher aware Events and Listeners

.. versionadded:: 2.1
The ``Event`` object contains a reference to the invoking dispatcher since Symfony 2.1

The ``EventDispatcher`` always injects a reference to itself in the passed event
object. This means that all listeners have direct access to the
``EventDispatcher`` object that notified the listener via the passed ``Event``
object's :method:`Symfony\\Component\\EventDispatcher\\Event::getDispatcher`
This was removed in Symfony 2.3

.. versionadded:: 2.3
The ``EventDispactherAwareEvent`` object contains a reference to the invoking dispatcher
since Symfony 2.3

The ``EventDispatcher`` will inject a reference to itself in the passed event
object if that event object is an instance of
:class:`Symfony\\Component\\EventDispatcher\\EventDispatcherAwareEvent`.
This means that all listeners have direct access to the
``EventDispatcher`` object that notified the listener via the
:method:`Symfony\\Component\\EventDispatcher\\EventDispatcherAwareEvent::getDispatcher`
method.

This can lead to some advanced applications of the ``EventDispatcher`` including
Expand All @@ -455,14 +462,14 @@ more listeners into the dispatcher object. Examples follow:

Lazy loading listeners::

use Symfony\Component\EventDispatcher\Event;
use Symfony\Component\EventDispatcher\EventDispatcherAwareEvent;
use Acme\StoreBundle\Event\StoreSubscriber;

class Foo
{
private $started = false;

public function myLazyListener(Event $event)
public function myLazyListener(EventDispatcherAwareEvent $event)
{
if (false === $this->started) {
$subscriber = new StoreSubscriber();
Expand All @@ -477,11 +484,11 @@ Lazy loading listeners::

Dispatching another event from within a listener::

use Symfony\Component\EventDispatcher\Event;
use Symfony\Component\EventDispatcher\EventDispatcherAwareEvent;

class Foo
{
public function myFooListener(Event $event)
public function myFooListener(EventDispatcherAwareEvent $event)
{
$event->getDispatcher()->dispatch('log', $event);

Expand Down Expand Up @@ -538,7 +545,7 @@ Dispatcher Shortcuts
.. versionadded:: 2.1
``EventDispatcher::dispatch()`` method returns the event since Symfony 2.1.

The :method:`EventDispatcher::dispatch<Symfony\\Component\\EventDispatcher\\EventDispatcher::dispatch>`
The :method:`EventDispatcher::dispatch<Symfony\\Component\\EventDispatcher\\EventDispatcher::dispatch()`
method always returns an :class:`Symfony\\Component\\EventDispatcher\\Event`
object. This allows for various shortcuts. For example if one does not need
a custom event object, one can simply rely on a plain
Expand Down