Skip to content

Commit 2a26572

Browse files
committed
bug #8649 Revamped the reference/events.rst article (javiereguiluz)
This PR was squashed before being merged into the 2.7 branch (closes #8649). Discussion ---------- Revamped the reference/events.rst article While upgrading some contents yesterday, I realized that this article is not as good as it should be, considering how important it is. The changes I propose: * For each event, clearly explain when it's dispatched and what you can do with it (without duplicating the full explanations found in `components/http_kernel.rst`) * Remove the tables showing the list of listeners/subscribers for each event. This is too hard to maintain and it depends on the components installed in your application. Let's mention the `debug:event-dispatcher` command instead. The last change is important because the information provided currently is wrong. See for example the Symfony Demo app: ![event-mismatch](https://user-images.githubusercontent.com/73419/32771545-48521732-c923-11e7-9c20-af7b40c37223.png) Commits ------- 9703922 Fixed RST syntax issue dff597e Revamped the reference/events.rst article
2 parents d82c7e6 + 9703922 commit 2a26572

File tree

1 file changed

+78
-102
lines changed

1 file changed

+78
-102
lines changed

reference/events.rst

Lines changed: 78 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
Symfony Framework Events
2-
========================
1+
Built-in Symfony Events
2+
=======================
33

4-
When the Symfony Framework (or anything using the :class:`Symfony\\Component\\HttpKernel\\HttpKernel`)
5-
handles a request, a few core events are dispatched so that you can add
6-
listeners throughout the process. These are called the "kernel events".
7-
For a larger explanation, see :doc:`/components/http_kernel`.
4+
During the handling of an HTTP request, the Symfony framework (or any
5+
application using the :doc:`HttpKernel component </components/http_kernel>`)
6+
dispatches some :doc:`events </event_dispatcher>` which you can use to modify
7+
how the request is handled.
88

99
Kernel Events
1010
-------------
1111

12-
Each event dispatched by the kernel is a subclass of
13-
:class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`. This means
14-
that each event has access to the following information:
12+
Each event dispatched by the HttpKernel component is a subclass of
13+
:class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`, which provides the
14+
following information:
1515

1616
:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
1717
Returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST``
@@ -31,67 +31,60 @@ that each event has access to the following information:
3131
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`
3232

3333
This event is dispatched very early in Symfony, before the controller is
34-
determined.
34+
determined. It's useful to add information to the Request or return a Response
35+
early to stop the handling of the request.
3536

3637
.. seealso::
3738

3839
Read more on the :ref:`kernel.request event <component-http-kernel-kernel-request>`.
3940

40-
These are the built-in Symfony listeners registered to this event:
41+
Execute this command to know the listeners registered to this event and their
42+
priorities:
4143

42-
============================================================================= ========
43-
Listener Class Name Priority
44-
============================================================================= ========
45-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener` 1024
46-
:class:`Symfony\\Bundle\\FrameworkBundle\\EventListener\\TestSessionListener` 192
47-
:class:`Symfony\\Bundle\\FrameworkBundle\\EventListener\\SessionListener` 128
48-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\RouterListener` 32
49-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\LocaleListener` 16
50-
:class:`Symfony\\Component\\Security\\Http\\Firewall` 8
51-
============================================================================= ========
44+
.. code-block:: terminal
45+
46+
$ php bin/console debug:event-dispatcher kernel.request
5247
5348
``kernel.controller``
5449
~~~~~~~~~~~~~~~~~~~~~
5550

5651
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent`
5752

58-
This event can be an entry point used to modify the controller that should be executed::
53+
This event is dispatched after the controller to be executed has been resolved
54+
but before executing it. It's useful to initialize things later needed by the
55+
controller, such as `param converters`_, and even to change the controller
56+
entirely::
5957

6058
use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
6159

6260
public function onKernelController(FilterControllerEvent $event)
6361
{
64-
$controller = $event->getController();
6562
// ...
6663

6764
// the controller can be changed to any PHP callable
68-
$event->setController($controller);
65+
$event->setController($myCustomController);
6966
}
7067

7168
.. seealso::
7269

7370
Read more on the :ref:`kernel.controller event <component-http-kernel-kernel-controller>`.
7471

75-
This is the built-in Symfony listener related to this event:
72+
Execute this command to know the listeners registered to this event and their
73+
priorities:
74+
75+
.. code-block:: terminal
7676
77-
============================================================================== ========
78-
Listener Class Name Priority
79-
============================================================================== ========
80-
:class:`Symfony\\Component\\HttpKernel\\DataCollector\\RequestDataCollector` 0
81-
============================================================================== ========
77+
$ php bin/console debug:event-dispatcher kernel.controller
8278
8379
``kernel.view``
8480
~~~~~~~~~~~~~~~
8581

8682
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForControllerResultEvent`
8783

88-
This event is not used by the FrameworkBundle, but it can be used to implement
89-
a view sub-system. This event is called *only* if the Controller does *not*
90-
return a ``Response`` object. The purpose of the event is to allow some
91-
other return value to be converted into a ``Response``.
92-
93-
The value returned by the Controller is accessible via the ``getControllerResult()``
94-
method::
84+
This event is dispatched after the controller has been executed but *only* if
85+
the controller does *not* return a :class:`Symfony\\Component\\HttpFoundation\\Response`
86+
object. It's useful to transform the returned value (e.g. a string with some
87+
HTML contents) into the ``Response`` object needed by Symfony::
9588

9689
use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
9790
use Symfony\Component\HttpFoundation\Response;
@@ -110,13 +103,21 @@ method::
110103

111104
Read more on the :ref:`kernel.view event <component-http-kernel-kernel-view>`.
112105

106+
Execute this command to know the listeners registered to this event and their
107+
priorities:
108+
109+
.. code-block:: terminal
110+
111+
$ php bin/console debug:event-dispatcher kernel.view
112+
113113
``kernel.response``
114114
~~~~~~~~~~~~~~~~~~~
115115

116116
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`
117117

118-
The purpose of this event is to allow other systems to modify or replace
119-
the ``Response`` object after its creation::
118+
This event is dispatched after the controller or any ``kernel.view`` listener
119+
returns a ``Response`` object. It's useful to modify or replace the response
120+
before sending it back (e.g. add/modify HTTP headers, add cookies, etc.)::
120121

121122
public function onKernelResponse(FilterResponseEvent $event)
122123
{
@@ -125,90 +126,64 @@ the ``Response`` object after its creation::
125126
// ... modify the response object
126127
}
127128

128-
The FrameworkBundle registers several listeners:
129-
130-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener`
131-
Collects data for the current request.
132-
133-
:class:`Symfony\\Bundle\\WebProfilerBundle\\EventListener\\WebDebugToolbarListener`
134-
Injects the Web Debug Toolbar.
135-
136-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ResponseListener`
137-
Fixes the Response ``Content-Type`` based on the request format.
138-
139-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\EsiListener`
140-
Adds a ``Surrogate-Control`` HTTP header when the Response needs to
141-
be parsed for ESI tags.
142-
143129
.. seealso::
144130

145131
Read more on the :ref:`kernel.response event <component-http-kernel-kernel-response>`.
146132

147-
These are the built-in Symfony listeners registered to this event:
133+
Execute this command to know the listeners registered to this event and their
134+
priorities:
135+
136+
.. code-block:: terminal
148137
149-
=================================================================================== ========
150-
Listener Class Name Priority
151-
=================================================================================== ========
152-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\EsiListener` 0
153-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ResponseListener` 0
154-
:class:`Symfony\\Component\\Security\\Http\\RememberMe\\ResponseListener` 0
155-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener` -100
156-
:class:`Symfony\\Bundle\\FrameworkBundle\\EventListener\\TestSessionListener` -128
157-
:class:`Symfony\\Bundle\\WebProfilerBundle\\EventListener\\WebDebugToolbarListener` -128
158-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\StreamedResponseListener` -1024
159-
=================================================================================== ========
138+
$ php bin/console debug:event-dispatcher kernel.response
160139
161140
``kernel.finish_request``
162141
~~~~~~~~~~~~~~~~~~~~~~~~~
163142

164143
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\FinishRequestEvent`
165144

166-
The purpose of this event is to allow you to reset the global and environmental
167-
state of the application after a sub-request has finished (for example, the
168-
translator listener resets the translator's locale to the one of the parent
169-
request)::
145+
This event is dispatched after a :ref:`sub request <http-kernel-sub-requests>`
146+
has finished. It's useful to reset the global state of the application (for
147+
example, the translator listener resets the translator's locale to the one of
148+
the parent request)::
170149

171150
public function onKernelFinishRequest(FinishRequestEvent $event)
172151
{
173152
if (null === $parentRequest = $this->requestStack->getParentRequest()) {
174153
return;
175154
}
176155

177-
//Reset the locale of the subrequest to the locale of the parent request
156+
// Reset the locale of the subrequest to the locale of the parent request
178157
$this->setLocale($parentRequest);
179158
}
180159

181-
These are the built-in Symfony listeners related to this event:
160+
Execute this command to know the listeners registered to this event and their
161+
priorities:
182162

183-
========================================================================== ========
184-
Listener Class Name Priority
185-
========================================================================== ========
186-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\LocaleListener` 0
187-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\TranslatorListener` 0
188-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\RouterListener` 0
189-
:class:`Symfony\\Component\\Security\\Http\\Firewall` 0
190-
========================================================================== ========
163+
.. code-block:: terminal
164+
165+
$ php bin/console debug:event-dispatcher kernel.finish_request
191166
192167
``kernel.terminate``
193168
~~~~~~~~~~~~~~~~~~~~
194169

195170
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\PostResponseEvent`
196171

197-
The purpose of this event is to perform tasks after the response was already
198-
served to the client.
172+
This event is dispatched after the response has been sent (after the execution
173+
of the :method:`Symfony\\Component\\HttpKernel\\HttpKernel::handle` method).
174+
It's useful to perform slow or complex tasks that don't need to be completed to
175+
send the response (e.g. sending emails).
199176

200177
.. seealso::
201178

202179
Read more on the :ref:`kernel.terminate event <component-http-kernel-kernel-terminate>`.
203180

204-
This is the built-in Symfony listener related to this event:
181+
Execute this command to know the listeners registered to this event and their
182+
priorities:
205183

206-
========================================================================= ========
207-
Listener Class Name Priority
208-
========================================================================= ========
209-
`EmailSenderListener`_ 0
210-
========================================================================= ========
184+
.. code-block:: terminal
211185
186+
$ php bin/console debug:event-dispatcher kernel.terminate
212187
213188
.. _kernel-kernel.exception:
214189

@@ -217,12 +192,9 @@ Listener Class Name Prior
217192

218193
**Event Class**: :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`
219194

220-
The TwigBundle registers an :class:`Symfony\\Component\\HttpKernel\\EventListener\\ExceptionListener`
221-
that forwards the ``Request`` to a given controller defined by the
222-
``exception_listener.controller`` parameter.
223-
224-
A listener on this event can create and set a ``Response`` object, create
225-
and set a new ``Exception`` object, or do nothing::
195+
This event is dispatched as soon as an error occurs during the handling of the
196+
HTTP request. It's useful to recover from errors or modify the exception details
197+
sent as response::
226198

227199
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
228200
use Symfony\Component\HttpFoundation\Response;
@@ -239,6 +211,12 @@ and set a new ``Exception`` object, or do nothing::
239211
// $event->setException($exception);
240212
}
241213

214+
.. note::
215+
216+
The TwigBundle registers an :class:`Symfony\\Component\\HttpKernel\\EventListener\\ExceptionListener`
217+
that forwards the ``Request`` to a given controller defined by the
218+
``exception_listener.controller`` parameter.
219+
242220
.. note::
243221

244222
Symfony uses the following logic to determine the HTTP status code of the
@@ -260,13 +238,11 @@ and set a new ``Exception`` object, or do nothing::
260238

261239
Read more on the :ref:`kernel.exception event <component-http-kernel-kernel-exception>`.
262240

263-
These are the built-in Symfony listeners registered to this event:
241+
Execute this command to know the listeners registered to this event and their
242+
priorities:
243+
244+
.. code-block:: terminal
264245
265-
========================================================================= ========
266-
Listener Class Name Priority
267-
========================================================================= ========
268-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener` 0
269-
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ExceptionListener` -128
270-
========================================================================= ========
246+
$ php bin/console debug:event-dispatcher kernel.exception
271247
272-
.. _`EmailSenderListener`: https://github.com/symfony/swiftmailer-bundle/blob/master/EventListener/EmailSenderListener.php
248+
.. _`param converters`: https://symfony.com/doc/master/bundles/SensioFrameworkExtraBundle/annotations/converters.html

0 commit comments

Comments
 (0)