Updated the doc for monolog

This describes the changes done in symfony/symfony#1556.

Author: stof

cookbook/logging/monolog.rst

@@ -163,65 +163,15 @@ only for a specific handler.
 
 A processor is simply a callable receiving the record as it's first argument.
 
-This example configuration shows you how to define a processor as a service,
-as a callback, or how you can simply use one of the core processors, which
-are called ``monolog.processor.<processor_name>``. At the moment, the ``web``
-and ``introspection`` processors are available in core.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        services:
-            my_processor:
-                class: Acme\MyBundle\MyFirstProcessor
-        monolog:
-            handlers:
-                file:
-                    type: stream
-                    level: debug
-                    processors:
-                        - Acme\MyBundle\MySecondProcessor::process
-            processors:
-                - @my_processor
-                - @monolog.processor.web
-
-    .. code-block:: xml
-
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xmlns:monolog="http://symfony.com/schema/dic/monolog"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                                http://symfony.com/schema/dic/monolog http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
-
-            <services>
-                <service id="my_processor" class="Acme\MyBundle\MyFirstProcessor" />
-            </services>
-            <monolog:config>
-                <monolog:handler
-                    name="file"
-                    type="stream"
-                    level="debug"
-                    formatter="my_formatter"
-                >
-                    <monolog:processor callback="Acme\MyBundle\MySecondProcessor::process" />
-                </monolog:handler />
-                <monolog:processor callback="@my_processor" />
-                <monolog:processor callback="@monolog.processor.web" />
-            </monolog:config>
-        </container>
-
-.. tip::
-
-    If you need some dependencies in your processor you can define a
-    service and implement the ``__invoke`` method on the class to make
-    it callable. You can then add it in the processor stack.
+Processors are configured using the ``monolog.processor`` DIC tag. See the
+:ref:`reference about it<dic_tags-monolog-processor>`.
 
 Adding a Session/Request Token
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sometimes it is hard to tell which entries in the log belong to which session
-and/or request. The following example will add a unique token for each request.
+and/or request. The following example will add a unique token for each request
+using a processor.
 
 .. code-block:: php
 
@@ -239,7 +189,7 @@ and/or request. The following example will add a unique token for each request.
             $this->session = $session;
         }
 
-        public function __invoke(array $record)
+        public function processRecord(array $record)
         {
             if (null === $this->token) {
                 try {
@@ -268,6 +218,8 @@ and/or request. The following example will add a unique token for each request.
             monolog.processor.session_request:
                 class: Acme\MyBundle\SessionRequestProcessor
                 arguments:  [ @session ]
+                tags:
+                    - { name: monolog.processor, method: processRecord }
 
         monolog:
             handlers:
@@ -276,7 +228,6 @@ and/or request. The following example will add a unique token for each request.
                     path: %kernel.logs_dir%/%kernel.environment%.log
                     level: debug
                     formatter: monolog.formatter.session_request
-            processors: [ @monolog.processor.session_request ]
 
 .. note::
 

reference/configuration/monolog.rst

@@ -18,8 +18,6 @@ Configuration Reference
                     level:               ERROR
                     bubble:              false
                     formatter:           my_formatter
-                    processors:
-                        - some_callable
                 main:
                     type:                fingerscrossed
                     action_level:        WARNING
@@ -48,13 +46,10 @@ Configuration Reference
                     from_email:           ~
                     to_email:             ~
                     subject:              ~
-                    email_prototype:      ~
+                    email_prototype:
+                        id:     ~ # Required (when the email_prototype is used)
+                        method: ~
                     formatter:            ~
-                    processors:           []
-            processors:
-
-                # Example:
-                - @my_processor
 
     .. code-block:: xml
 
@@ -72,9 +67,7 @@ Configuration Reference
                     level="error"
                     bubble="false"
                     formatter="my_formatter"
-                >
-                    <monolog:processor callback="some_callable" />
-                </monolog:handler>
+                />
                 <monolog:handler
                     name="main"
                     type="fingerscrossed"
@@ -86,7 +79,6 @@ Configuration Reference
                     type="service"
                     id="my_handler"
                 />
-                <monolog:processor callback="@my_processor" />
             </monolog:config>
         </container>
 

reference/dic_tags.rst

@@ -4,11 +4,18 @@ The Dependency Injection Tags
 Tags:
 
 * ``data_collector``
+* ``form.type``
+* ``form.type_extension``
+* ``form.type_guesser``
+* ``kernel.cache_warmer``
 * ``kernel.event_listener``
+* ``monolog.logger``
+* ``monolog.processor``
 * ``templating.helper``
-* ``templating.renderer``
 * ``routing.loader``
+* ``translation.loader``
 * ``twig.extension``
+* ``validator.initializer``
 
 Enabling Custom PHP Template Helpers
 ------------------------------------
@@ -204,3 +211,101 @@ channel when injecting the logger in a service.
 
     This works only when the logger service is a constructor argument,
     not when it is injected through a setter.
+
+.. _dic_tags-monolog-processor:
+
+Adding a processor for Monolog
+------------------------------
+
+Monolog allows to add processors in the logger or in the handlers to add
+extra data in the records. A processor receives the record as argument and
+must return it after adding eventually some extra data in the ``extra``
+attribute of the record.
+
+Let's see how you can use the built-in IntrospectionProcessor to add the file,
+the line, the class and the method where the logger was triggered.
+
+You can add a processor globally:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            my_service:
+                class: Monolog\Processor\IntrospectionProcessor
+                tags:
+                    - { name: monolog.processor }
+
+    .. code-block:: xml
+
+        <service id="my_service" class="Monolog\Processor\IntrospectionProcessor">
+            <tag name="monolog.processor" />
+        </service>
+
+    .. code-block:: php
+
+        $definition = new Definition('Monolog\Processor\IntrospectionProcessor');
+        $definition->addTag('monolog.processor');
+        $container->register('my_service', $definition);
+
+.. tip::
+
+    If your service is not a callable (using ``__invoke``) you can add the
+    ``method`` attribute in the tag to use a specific method.
+
+You can add also a processor for a specific handler by using the ``handler``
+attribute:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            my_service:
+                class: Monolog\Processor\IntrospectionProcessor
+                tags:
+                    - { name: monolog.processor, handler: firephp }
+
+    .. code-block:: xml
+
+        <service id="my_service" class="Monolog\Processor\IntrospectionProcessor">
+            <tag name="monolog.processor" handler="firephp" />
+        </service>
+
+    .. code-block:: php
+
+        $definition = new Definition('Monolog\Processor\IntrospectionProcessor');
+        $definition->addTag('monolog.processor', array('handler' => 'firephp');
+        $container->register('my_service', $definition);
+
+You can add also a processor for a specific logging by using the ``channel``
+attribute. This will register the processor only for the ``security`` logging
+channel used in the Security component:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            my_service:
+                class: Monolog\Processor\IntrospectionProcessor
+                tags:
+                    - { name: monolog.processor, channel: security }
+
+    .. code-block:: xml
+
+        <service id="my_service" class="Monolog\Processor\IntrospectionProcessor">
+            <tag name="monolog.processor" channel="security" />
+        </service>
+
+    .. code-block:: php
+
+        $definition = new Definition('Monolog\Processor\IntrospectionProcessor');
+        $definition->addTag('monolog.processor', array('channel' => 'security');
+        $container->register('my_service', $definition);
+
+.. note::
+
+    You cannot use both the ``handler`` and ``channel`` attributes for the
+    same tag as handlers are shared between all channels.