Added a note about the priority meaning in event subscribers

Conflicts:
	cookbook/service_container/event_listener.rst

Author: beni0888

cookbook/event_dispatcher/event_listener.rst

@@ -1,27 +1,34 @@
 .. index::
    single: Events; Create listener
+   single: 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
-you to modify how exceptions are shown by your application. The ``KernelEvents::EXCEPTION``
-event is just one of the core kernel events::
+a service that listens to 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.
 
-    // src/AppBundle/EventListener/AcmeExceptionListener.php
+Creating an Event Listener
+--------------------------
+
+The most common way to listen to an event is to register an event listener::
+
+    // 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)
         {
@@ -43,26 +50,23 @@ event is just one of the core kernel events::
                 $response->setStatusCode($exception->getStatusCode());
                 $response->headers->replace($exception->getHeaders());
             } else {
-                $response->setStatusCode(500);
+                $response->setStatusCode(Response::HTTP_INTERNAL_SERVER_ERROR);
             }
 
             // Send the modified response object to the event
             $event->setResponse($response);
         }
     }
 
+.. versionadded:: 2.4
+    Support for HTTP status code constants was introduced in Symfony 2.4.
+
 .. tip::
 
     Each event receives a slightly different type of ``$event`` object. For
     the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`.
     To see what type of object each event listener receives, see :class:`Symfony\\Component\\HttpKernel\\KernelEvents`.
 
-.. note::
-
-    When setting a response for the ``kernel.request``, ``kernel.view`` or
-    ``kernel.exception`` events, the propagation is stopped, so the lower
-    priority listeners on that event don't get called.
-
 Now that the class is created, you just need to register it as a service and
 notify Symfony that it is a "listener" on the ``kernel.exception`` event by
 using a special "tag":
@@ -71,7 +75,7 @@ using a special "tag":
 
     .. code-block:: yaml
 
-        # app/config/services.yml
+        # app/config/config.yml
         services:
             kernel.listener.your_listener_name:
                 class: AppBundle\EventListener\AcmeExceptionListener
@@ -80,14 +84,14 @@ using a special "tag":
 
     .. code-block:: xml
 
-        <!-- app/config/services.xml -->
+        <!-- app/config/config.xml -->
         <service id="kernel.listener.your_listener_name" class="AppBundle\EventListener\AcmeExceptionListener">
             <tag name="kernel.event_listener" event="kernel.exception" method="onKernelException" />
         </service>
 
     .. code-block:: php
 
-        // app/config/services.php
+        // app/config/config.php
         $container
             ->register('kernel.listener.your_listener_name', 'AppBundle\EventListener\AcmeExceptionListener')
             ->addTag('kernel.event_listener', array('event' => 'kernel.exception', 'method' => 'onKernelException'))
@@ -96,12 +100,124 @@ using a special "tag":
 .. note::
 
     There is an additional tag option ``priority`` that is optional and defaults
-    to 0. The listeners will be executed in the order of their priority (highest to lowest).
-    This is useful when you need to guarantee that one listener is executed before another.
+    to 0. This value can be from -255 to 255, and the listeners will be executed
+    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 methods that listen to one or various events,
+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 :doc:`/components/event_dispatcher/introduction`.
+The following example shows a subscriber that subscribes various methods
+to the ``kernel.exception`` event::
+
+    // src/AppBundle/EventListener/ExceptionSubscriber.php
+    namespace AppBundle\EventSubscriber;
+
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+
+    class ExceptionSubscriber 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: AppBundle\EventSubscriber\AcmeExceptionSubscriber
+                tags:
+                    - { name: kernel.event_subscriber }
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services">
+
+            <services>
+                <service id="acme_exception_subscriber"
+                    class="AppBundle\EventSubscriber\AcmeExceptionSubscriber">
+
+                    <tag name="kernel.event_subscriber"/>
+
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container
+            ->register(
+                'acme_exception_subscriber',
+                'AppBundle\EventSubscriber\AcmeExceptionSubscriber'
+            )
+            ->addTag('kernel.event_subscriber')
+        ;
 
 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
@@ -117,7 +233,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;
             }
@@ -131,3 +247,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