1
- Symfony Framework Events
2
- ========================
1
+ Built-in Symfony Events
2
+ =======================
3
3
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 .
8
8
9
9
Kernel Events
10
10
-------------
11
11
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:
15
15
16
16
:method: `Symfony\\ Component\\ HttpKernel\\ Event\\ KernelEvent::getRequestType `
17
17
Returns the *type * of the request (``HttpKernelInterface::MASTER_REQUEST ``
@@ -31,67 +31,60 @@ that each event has access to the following information:
31
31
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ GetResponseEvent `
32
32
33
33
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.
35
36
36
37
.. seealso ::
37
38
38
39
Read more on the :ref: `kernel.request event <component-http-kernel-kernel-request >`.
39
40
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:
41
43
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
52
47
53
48
``kernel.controller ``
54
49
~~~~~~~~~~~~~~~~~~~~~
55
50
56
51
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ FilterControllerEvent `
57
52
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::
59
57
60
58
use Symfony\Component\HttpKernel\Event\FilterControllerEvent;
61
59
62
60
public function onKernelController(FilterControllerEvent $event)
63
61
{
64
- $controller = $event->getController();
65
62
// ...
66
63
67
64
// the controller can be changed to any PHP callable
68
- $event->setController($controller );
65
+ $event->setController($myCustomController );
69
66
}
70
67
71
68
.. seealso ::
72
69
73
70
Read more on the :ref: `kernel.controller event <component-http-kernel-kernel-controller >`.
74
71
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
76
76
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
82
78
83
79
``kernel.view ``
84
80
~~~~~~~~~~~~~~~
85
81
86
82
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ GetResponseForControllerResultEvent `
87
83
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::
95
88
96
89
use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
97
90
use Symfony\Component\HttpFoundation\Response;
@@ -110,13 +103,21 @@ method::
110
103
111
104
Read more on the :ref: `kernel.view event <component-http-kernel-kernel-view >`.
112
105
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
+
113
113
``kernel.response ``
114
114
~~~~~~~~~~~~~~~~~~~
115
115
116
116
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ FilterResponseEvent `
117
117
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.)::
120
121
121
122
public function onKernelResponse(FilterResponseEvent $event)
122
123
{
@@ -125,90 +126,64 @@ the ``Response`` object after its creation::
125
126
// ... modify the response object
126
127
}
127
128
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
-
143
129
.. seealso ::
144
130
145
131
Read more on the :ref: `kernel.response event <component-http-kernel-kernel-response >`.
146
132
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
148
137
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
160
139
161
140
``kernel.finish_request ``
162
141
~~~~~~~~~~~~~~~~~~~~~~~~~
163
142
164
143
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ FinishRequestEvent `
165
144
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)::
170
149
171
150
public function onKernelFinishRequest(FinishRequestEvent $event)
172
151
{
173
152
if (null === $parentRequest = $this->requestStack->getParentRequest()) {
174
153
return;
175
154
}
176
155
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
178
157
$this->setLocale($parentRequest);
179
158
}
180
159
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:
182
162
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
191
166
192
167
``kernel.terminate ``
193
168
~~~~~~~~~~~~~~~~~~~~
194
169
195
170
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ PostResponseEvent `
196
171
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).
199
176
200
177
.. seealso ::
201
178
202
179
Read more on the :ref: `kernel.terminate event <component-http-kernel-kernel-terminate >`.
203
180
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:
205
183
206
- ========================================================================= ========
207
- Listener Class Name Priority
208
- ========================================================================= ========
209
- `EmailSenderListener `_ 0
210
- ========================================================================= ========
184
+ .. code-block :: terminal
211
185
186
+ $ php bin/console debug:event-dispatcher kernel.terminate
212
187
213
188
.. _kernel-kernel.exception :
214
189
@@ -217,12 +192,9 @@ Listener Class Name Prior
217
192
218
193
**Event Class **: :class: `Symfony\\ Component\\ HttpKernel\\ Event\\ GetResponseForExceptionEvent `
219
194
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::
226
198
227
199
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
228
200
use Symfony\Component\HttpFoundation\Response;
@@ -239,6 +211,12 @@ and set a new ``Exception`` object, or do nothing::
239
211
// $event->setException($exception);
240
212
}
241
213
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
+
242
220
.. note ::
243
221
244
222
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::
260
238
261
239
Read more on the :ref: `kernel.exception event <component-http-kernel-kernel-exception >`.
262
240
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
264
245
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
271
247
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