Skip to content

Updated event_listener.rst #3776

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

Merged
merged 4 commits into from
May 27, 2014
Merged

Updated event_listener.rst #3776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0127bd2
Updated event_listener.rst
bfgasparin Apr 7, 2014
8e8b8a0
Added Versionadded directive to event_listener.rst
bfgasparin Apr 8, 2014
a6b17a0
Added KernelEvent::isMasterRequest method reference
Apr 10, 2014
4fc3b6a
Fixed internals.rst syntax
bfgasparin Apr 10, 2014
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
15 changes: 11 additions & 4 deletions book/internals.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,10 @@ processing must only occur on the master request).
Events
~~~~~~

.. versionadded:: 2.4
The ``isMasterRequest()`` method was introduced in Symfony 2.4.
Prior, the ``getRequestType()`` method must be used.

Each event thrown by the Kernel is a subclass of
:class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`. This means that
each event has access to the same basic information:
Expand All @@ -216,22 +220,25 @@ each event has access to the same basic information:
- returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST``
or ``HttpKernelInterface::SUB_REQUEST``);

* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::isMasterRequest`
- checks if it is a master request;

* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getKernel`
- returns the Kernel handling the request;

* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequest`
- returns the current ``Request`` being handled.

``getRequestType()``
....................
``isMasterRequest()``
.....................

The ``getRequestType()`` method allows listeners to know the type of the
The ``isMasterRequest()`` method allows listeners to check the type of the
request. For instance, if a listener must only be active for master requests,
add the following code at the beginning of your listener method::

use Symfony\Component\HttpKernel\HttpKernelInterface;

if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
if (!$event->isMasterRequest()) {
// return immediately
return;
}
Expand Down
10 changes: 7 additions & 3 deletions components/http_kernel/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -665,12 +665,16 @@ argument as follows::
$response = $kernel->handle($request, HttpKernelInterface::SUB_REQUEST);
// do something with this response

.. versionadded:: 2.4
The ``isMasterRequest()`` method was introduced in Symfony 2.4.
Prior, the ``getRequestType()`` method must be used.

This creates another full request-response cycle where this new ``Request`` is
transformed into a ``Response``. The only difference internally is that some
listeners (e.g. security) may only act upon the master request. Each listener
is passed some sub-class of :class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`,
whose :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
can be used to figure out if the current request is a "master" or "sub" request.
whose :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::isMasterRequest`
can be used to check if the current request is a "master" or "sub" request.

For example, a listener that only needs to act on the master request may
look like this::
Expand All @@ -680,7 +684,7 @@ look like this::

public function onKernelRequest(GetResponseEvent $event)
{
if (HttpKernelInterface::MASTER_REQUEST !== $event->getRequestType()) {
if (!$event->isMasterRequest()) {
return;
}

Expand Down
6 changes: 5 additions & 1 deletion cookbook/service_container/event_listener.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,10 @@ using a special "tag":
Request events, checking types
------------------------------

.. versionadded:: 2.4
The ``isMasterRequest()`` method was introduced in Symfony 2.4.
Prior, the ``getRequestType()`` method must be used.

A single page can make several requests (one master request, and then multiple
sub-requests), which is why when working with the ``KernelEvents::REQUEST``
event, you might need to check the type of the request. This can be easily
Expand All @@ -115,7 +119,7 @@ done as follow::
{
public function onKernelRequest(GetResponseEvent $event)
{
if (HttpKernel::MASTER_REQUEST != $event->getRequestType()) {
if (!$event->isMasterRequest()) {
// don't do anything if it's not the master request
return;
}
Expand Down