From bb9818a3259dd8445056abddff7378097787ca45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Sat, 29 Nov 2014 12:00:52 +0100 Subject: [PATCH 01/14] Added "How to create an event subscriber" I've added the information about how to create an event subscriber to the "How to create an Event listener" cookbook recipe. --- cookbook/service_container/event_listener.rst | 110 +++++++++++++++++- 1 file changed, 104 insertions(+), 6 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 00b66670a48..be6bfff9579 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -1,18 +1,24 @@ .. index:: - single: Events; Create listener + single: Events; Create listener, Create subscriber -How to Create an Event Listener -=============================== +How to Create Event Listeners and Subscribers +============================================= Symfony has various events and hooks that can be used to trigger custom behavior in your application. Those events are thrown by the HttpKernel component and can be viewed in the :class:`Symfony\\Component\\HttpKernel\\KernelEvents` class. To hook into an event and add your own custom logic, you have to create -a service that will act as an event listener on that event. In this entry, -you will create a service that will act as an Exception Listener, allowing +a service that will act as an event listener on that event. You can do that in two different ways, +creating an Event Listener or an Event Subscriber instead. In this entry, +you will see the two ways of creating a service that will act as an Exception Listener, allowing you to modify how exceptions are shown by your application. The ``KernelEvents::EXCEPTION`` -event is just one of the core kernel events:: +event is just one of the core kernel events. + +Creating an Event Listener +-------------------------- + +The most common way to listen to an event is to register an event listener: // src/Acme/DemoBundle/EventListener/AcmeExceptionListener.php namespace Acme\DemoBundle\EventListener; @@ -97,6 +103,98 @@ using a special "tag": in the order of their priority (highest to lowest). This is useful when you need to guarantee that one listener is executed before another. +Creating an Event Subscriber +---------------------------- + +Another way to listen to events is via an event subscriber. An event subscriber can define one or various method +that listen to one or various events, and can stablish a priority for each method. The following example shows +a subscriber that subscribes various methods to the kernel.exception event: + + // src/Acme/DemoBundle/EventListener/AcmeExceptionSubscriber.php + namespace Acme\DemoBundle\EventSubscriber; + + use Symfony\Component\EventDispatcher\EventSubscriberInterface; + use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface; + + class AcmeExceptionSubscriber implements EventSubscriberInterface + { + public static function getSubscribedEvents() + { + // Return the events it is subscribed to, the methods that listen each event and the + // priority of each method + return array( + 'kernel.exception' => array( + array('onKernelExceptionPre', 10), + array('onKernelExceptionMid', 5), + array('onKernelExceptionPost', 0), + ) + ); + } + + public function onKernelExceptionPre(GetResponseForExceptionEvent $event) + { + $exception = $event->getException(); + $message = sprintf( + 'My Error says: %s with code: %s', + $exception->getMessage(), + $exception->getCode() + ); + + $response = new Response(); + $response->setContent($message); + + if ($exception instanceof HttpExceptionInterface) { + $response->setStatusCode($exception->getStatusCode()); + $response->headers->replace($exception->getHeaders()); + } else { + $response->setStatusCode(Response::HTTP_INTERNAL_SERVER_ERROR); + } + + $event->setResponse($response); + } + + public function onKernerlExceptionMid(GetResponseForExceptionEvent $event) + { + // ... + } + + public function onKernerlExceptionPost(GetResponseForExceptionEvent $event) + { + // ... + } + } + +Now, you just need to register the class as a service and notify Symfony that it +is an event subscriber: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + services: + kernel.listener.your_subscriber_name: + class: Acme\DemoBundle\EventSubscriber\AcmeExceptionSubscriber + tags: + - { name: kernel.event_subscriber } + + .. code-block:: xml + + + + + + + .. code-block:: php + + // app/config/config.php + $container + ->register('kernel.listener.your_subscriber_name', 'Acme\DemoBundle\EventSubscriber\AcmeExceptionSubscriber') + ->addTag('kernel.event_subscriber')) + ; + Request Events, Checking Types ------------------------------ From a6348b2331188849120537629dca842ec876d601 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Sat, 29 Nov 2014 12:31:36 +0100 Subject: [PATCH 02/14] Fixed error in index definition I've fixed my previous error in the definition of an index entry. --- cookbook/service_container/event_listener.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index be6bfff9579..70fae6aa442 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -1,5 +1,6 @@ .. index:: - single: Events; Create listener, Create subscriber + single: Events; Create listener + single: Create subscriber How to Create Event Listeners and Subscribers ============================================= From 900a70ede2b11b70af3fe490c35eec876cef3955 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Sat, 29 Nov 2014 14:44:15 +0100 Subject: [PATCH 03/14] Added double colon (::) --- cookbook/service_container/event_listener.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 70fae6aa442..7c98c8000d9 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -19,7 +19,7 @@ event is just one of the core kernel events. Creating an Event Listener -------------------------- -The most common way to listen to an event is to register an event listener: +The most common way to listen to an event is to register an event listener:: // src/Acme/DemoBundle/EventListener/AcmeExceptionListener.php namespace Acme\DemoBundle\EventListener; From be3143c0085bf2a3707fe7adba103db01da42787 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 18:27:58 +0100 Subject: [PATCH 04/14] Breaked too long lines --- cookbook/service_container/event_listener.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 7c98c8000d9..f929bc8792b 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -107,9 +107,10 @@ using a special "tag": Creating an Event Subscriber ---------------------------- -Another way to listen to events is via an event subscriber. An event subscriber can define one or various method -that listen to one or various events, and can stablish a priority for each method. The following example shows -a subscriber that subscribes various methods to the kernel.exception event: +Another way to listen to events is via an event subscriber. An event subscriber +can define one or various method that listen to one or various events, +and can stablish a priority for each method. The following example shows +a subscriber that subscribes various methods to the kernel.exception event:: // src/Acme/DemoBundle/EventListener/AcmeExceptionSubscriber.php namespace Acme\DemoBundle\EventSubscriber; From 5084c5a818bcb1281c78ba54a81fbd15ee5288f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 18:28:56 +0100 Subject: [PATCH 05/14] Removed vendors --- cookbook/service_container/event_listener.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index f929bc8792b..b48af48df6b 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -116,9 +116,6 @@ a subscriber that subscribes various methods to the kernel.exception event:: namespace Acme\DemoBundle\EventSubscriber; use Symfony\Component\EventDispatcher\EventSubscriberInterface; - use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; - use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface; class AcmeExceptionSubscriber implements EventSubscriberInterface { From bec7cf9eac5d791ac6fb70434dd519a6fc85b802 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 18:34:14 +0100 Subject: [PATCH 06/14] Changed xml service definition example --- cookbook/service_container/event_listener.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index b48af48df6b..0600ca1364b 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -182,9 +182,18 @@ is an event subscriber: .. code-block:: xml - - - + + + + + + + + + + + .. code-block:: php From 626ddca92583729352b204cdf5bd51263acb7e59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 18:48:51 +0100 Subject: [PATCH 07/14] Wrapped php definition service example --- cookbook/service_container/event_listener.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 0600ca1364b..63fc8fae430 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -199,8 +199,11 @@ is an event subscriber: // app/config/config.php $container - ->register('kernel.listener.your_subscriber_name', 'Acme\DemoBundle\EventSubscriber\AcmeExceptionSubscriber') - ->addTag('kernel.event_subscriber')) + ->register( + 'acme_exception_subscriber', + 'Acme\DemoBundle\EventSubscriber\AcmeExceptionSubscriber' + ) + ->addTag('kernel.event_subscriber') ; Request Events, Checking Types From 2bca2c565a6fd5b7694f3aab1cc3f7f4423ac533 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 19:04:56 +0100 Subject: [PATCH 08/14] Corrected typo --- cookbook/service_container/event_listener.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 63fc8fae430..37f5f1cb3d9 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -109,7 +109,7 @@ Creating an Event Subscriber Another way to listen to events is via an event subscriber. An event subscriber can define one or various method that listen to one or various events, -and can stablish a priority for each method. The following example shows +and can set a priority for each method. The following example shows a subscriber that subscribes various methods to the kernel.exception event:: // src/Acme/DemoBundle/EventListener/AcmeExceptionSubscriber.php From 5d02ef7579dfcc77db70a61053875a4c1d889752 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 19:11:25 +0100 Subject: [PATCH 09/14] Added reference to EventDispatcher component --- cookbook/service_container/event_listener.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 37f5f1cb3d9..c997de38a11 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -109,8 +109,9 @@ Creating an Event Subscriber Another way to listen to events is via an event subscriber. An event subscriber can define one or various method that listen to one or various events, -and can set a priority for each method. The following example shows -a subscriber that subscribes various methods to the kernel.exception event:: +and can set a priority for each method. To learn more about event subscribers, +see `The EventDispatcher component`_. The following example shows a subscriber +that subscribes various methods to the kernel.exception event:: // src/Acme/DemoBundle/EventListener/AcmeExceptionSubscriber.php namespace Acme\DemoBundle\EventSubscriber; @@ -242,3 +243,5 @@ done as follow:: Two types of request are available in the :class:`Symfony\\Component\\HttpKernel\\HttpKernelInterface` interface: ``HttpKernelInterface::MASTER_REQUEST`` and ``HttpKernelInterface::SUB_REQUEST``. + +.. _`The EventDispatcher component`: http://symfony.com/doc/current/components/event_dispatcher/index.html \ No newline at end of file From 0ed66ecded1c43c590778bd281dde61731e878b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 19:21:53 +0100 Subject: [PATCH 10/14] Removed vendor from event subscriber class name --- cookbook/service_container/event_listener.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index c997de38a11..29279881b35 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -113,12 +113,15 @@ and can set a priority for each method. To learn more about event subscribers, see `The EventDispatcher component`_. The following example shows a subscriber that subscribes various methods to the kernel.exception event:: - // src/Acme/DemoBundle/EventListener/AcmeExceptionSubscriber.php + // src/Acme/DemoBundle/EventListener/ExceptionSubscriber.php namespace Acme\DemoBundle\EventSubscriber; use Symfony\Component\EventDispatcher\EventSubscriberInterface; + use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface; - class AcmeExceptionSubscriber implements EventSubscriberInterface + class ExceptionSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents() { From ab79a9cffb2f9e25a5d14905b4a858b366774394 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 19:58:26 +0100 Subject: [PATCH 11/14] "Uncapitalized" some words in the text to keep the same style as in the rest of the document. --- cookbook/service_container/event_listener.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 29279881b35..c19160d3368 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -11,8 +11,8 @@ component and can be viewed in the :class:`Symfony\\Component\\HttpKernel\\Kerne To hook into an event and add your own custom logic, you have to create a service that will act as an event listener on that event. You can do that in two different ways, -creating an Event Listener or an Event Subscriber instead. In this entry, -you will see the two ways of creating a service that will act as an Exception Listener, allowing +creating an event listener or an event subscriber instead. In this entry, +you will see the two ways of creating a service that will act as an exception listener, allowing you to modify how exceptions are shown by your application. The ``KernelEvents::EXCEPTION`` event is just one of the core kernel events. From 9aba4adbdf6731e864a43e2fdc11f5204c52e9ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 20:13:36 +0100 Subject: [PATCH 12/14] Fixed typos and syntax errors --- cookbook/service_container/event_listener.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index c19160d3368..abec7861424 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -108,10 +108,10 @@ Creating an Event Subscriber ---------------------------- Another way to listen to events is via an event subscriber. An event subscriber -can define one or various method that listen to one or various events, +can define one or various methods that listen to one or various events, and can set a priority for each method. To learn more about event subscribers, see `The EventDispatcher component`_. The following example shows a subscriber -that subscribes various methods to the kernel.exception event:: +that subscribes various methods to the ``kernel.exception`` event:: // src/Acme/DemoBundle/EventListener/ExceptionSubscriber.php namespace Acme\DemoBundle\EventSubscriber; From 00b16aea5246a9ccf464df14d2b393dc98db08bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 20:18:58 +0100 Subject: [PATCH 13/14] Changed the code of the examples to use AppBundle instead of a DemoBundle --- cookbook/service_container/event_listener.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index abec7861424..2579550f974 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -21,14 +21,14 @@ Creating an Event Listener The most common way to listen to an event is to register an event listener:: - // src/Acme/DemoBundle/EventListener/AcmeExceptionListener.php - namespace Acme\DemoBundle\EventListener; + // src/AppBundle/EventListener/ExceptionListener.php + namespace AppBundle\EventListener; use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface; - class AcmeExceptionListener + class ExceptionListener { public function onKernelException(GetResponseForExceptionEvent $event) { @@ -113,8 +113,8 @@ and can set a priority for each method. To learn more about event subscribers, see `The EventDispatcher component`_. The following example shows a subscriber that subscribes various methods to the ``kernel.exception`` event:: - // src/Acme/DemoBundle/EventListener/ExceptionSubscriber.php - namespace Acme\DemoBundle\EventSubscriber; + // src/AppBundle/EventListener/ExceptionSubscriber.php + namespace AppBundle\EventSubscriber; use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent; @@ -222,8 +222,8 @@ 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 done as follow:: - // src/Acme/DemoBundle/EventListener/AcmeRequestListener.php - namespace Acme\DemoBundle\EventListener; + // src/AppBundle/EventListener/AcmeRequestListener.php + namespace AppBundle\EventListener; use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\HttpKernel; From f8b769cd870b9e213b7eefebfb0b2d6f6cc3417c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Miguel=20Benito=20Calzada?= Date: Mon, 1 Dec 2014 20:24:37 +0100 Subject: [PATCH 14/14] Added a note about the priority meaning in event subscribers --- cookbook/service_container/event_listener.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/cookbook/service_container/event_listener.rst b/cookbook/service_container/event_listener.rst index 2579550f974..f75d8d5932c 100644 --- a/cookbook/service_container/event_listener.rst +++ b/cookbook/service_container/event_listener.rst @@ -109,9 +109,10 @@ Creating an Event Subscriber Another way to listen to events is via an event subscriber. An event subscriber can define one or various methods that listen to one or various events, -and can set a priority for each method. To learn more about event subscribers, -see `The EventDispatcher component`_. The following example shows a subscriber -that subscribes various methods to the ``kernel.exception`` event:: +and can set a priority for each method. The higher the priority, the earlier +the method is called. To learn more about event subscribers, see `The EventDispatcher component`_. +The following example shows a subscriber that subscribes various methods +to the ``kernel.exception`` event:: // src/AppBundle/EventListener/ExceptionSubscriber.php namespace AppBundle\EventSubscriber;