symfony · tvlooy · Dec 14, 2013
diff --git a/components/console/introduction.rst b/components/console/introduction.rst
@@ -160,6 +160,8 @@ You can also set these colors and options inside the tagname::
     // bold text on a yellow background
     $output->writeln('<bg=yellow;options=bold>foo</bg=yellow;options=bold>');
 
+.. verbosity-levels:
+
 Verbosity Levels
 ~~~~~~~~~~~~~~~~
 
@@ -226,6 +228,11 @@ When the quiet level is used, all output is suppressed as the default
 :method:`Symfony\Component\Console\Output::write <Symfony\\Component\\Console\\Output::write>`
 method returns without actually printing.
 
+.. tip::
+
+    You can use `MonologBundle`_ 2.4 to display messages on the console. This
+    is cleaner than wrapping your output calls in conditions (see :doc:/cookbook/logging/monolog_console).
+
 Using Command Arguments
 -----------------------
 
@@ -520,3 +527,4 @@ Learn More!
 
 .. _Packagist: https://packagist.org/packages/symfony/console
 .. _ANSICON: https://github.com/adoxa/ansicon/downloads
+.. _MonologBundle: https://github.com/symfony/MonologBundle
diff --git a/cookbook/logging/index.rst b/cookbook/logging/index.rst
@@ -6,5 +6,6 @@ Logging
 
     monolog
     monolog_email
+    monolog_console
     monolog_regex_based_excludes
     channels_handlers
diff --git a/cookbook/logging/monolog.rst b/cookbook/logging/monolog.rst
@@ -23,8 +23,7 @@ your controller::
     }
 
 The ``logger`` service has different methods for different logging levels.
-See :class:`Symfony\\Component\\HttpKernel\\Log\\LoggerInterface` for details
-on which methods are available.
+See LoggerInterface_ for details on which methods are available.
 
 Handlers and Channels: Writing logs to different Locations
 ----------------------------------------------------------
@@ -351,3 +350,4 @@ using a processor.
     handler level instead of globally.
 
 .. _Monolog: https://github.com/Seldaek/monolog
+.. _LoggerInterface: https://github.com/php-fig/log/blob/master/Psr/Log/LoggerInterface.php
diff --git a/cookbook/logging/monolog_console.rst b/cookbook/logging/monolog_console.rst
@@ -0,0 +1,176 @@
+.. index::
+   single: Logging; Console messages
+
+How to Configure Monolog to Display Console Messages
+====================================================
+
+It is possible to use the console to print messages for a certain :ref:`verbosity-levels`
+using the :class:`Symfony\\Component\\Console\\Output\\OutputInterface`
+instance that is passed when a command gets executed.
+
+When a lot of logging has to happen, it's cumbersome to print information
+depending on the verbosity settings (``-v``, ``-vv``, ``-vvv``) because the
+calls need to be wrapped in conditions. The code quickly gets verbose or dirty.
+For example::
+
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        if ($output->getVerbosity() >= OutputInterface::VERBOSITY_DEBUG) {
+            $output->writeln('Some info');
+        }
+
+        if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
+            $output->writeln('Some more info');
+        }
+    }
+
+Instead of using these semantic methods to test for each of the verbosity
+levels, `MonologBundle`_ 2.4 provides a `ConsoleHandler`_ that listens to
+console events and writes log messages to the console output depending on the
+current log level and the console verbosity.
+
+The example above could then be rewritten as::
+
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $logger->debug('Some info');
+
+        $logger->notice('Some more info');
+    }
+
+These messages will get displayed on the console, timestamped, colored
+depending on the log level and error logs are written to the error output
+(php://stderr). There is no need to conditionally handle the verbosity
+settings anymore.
+
+The Monolog console handler is enabled in the Monolog configuration. This is
+the default in Symfony Standard Edition 2.4 too.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        monolog:
+            handlers:
+                console:
+                    type: console
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:monolog="http://symfony.com/schema/dic/monolog">
+
+            <monolog:config>
+                <monolog:handler name="console" type="console" />
+            </monolog:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('monolog', array(
+            'handlers' => array(
+                'console' => array(
+                   'type' => 'console',
+                ),
+            ),
+        ));
+
+With the ``verbosity_levels`` option you can adapt the mapping between
+verbosity and log level. In the given example it will also show notices in
+normal verbosity mode (instead of warnings only). Additionally, it will only
+use messages logged with the custom ``my_channel`` channel and it changes the
+display style via a custom formatter. See also the :doc:`reference/configuration/monolog`
+for more information:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        monolog:
+            handlers:
+                console:
+                    type:   console
+                    verbosity_levels:
+                        VERBOSITY_NORMAL: NOTICE
+                    channels: my_channel
+                    formatter: my_formatter
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:monolog="http://symfony.com/schema/dic/monolog">
+
+            <monolog:config>
+                <monolog:handler name="console" type="console" formatter="my_formatter">
+                    <monolog:verbosity-level verbosity-normal="NOTICE" />
+                    <monolog:channel>my_channel</monolog:channel>
+                </monolog:handler>
+            </monolog:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('monolog', array(
+            'handlers' => array(
+                'console' => array(
+                    'type' => 'console',
+                    'verbosity_levels' => array(
+                        'VERBOSITY_NORMAL' => 'NOTICE',
+                    ),
+                    'channels' => 'my_channel',
+                    'formatter' => 'my_formatter',
+                ),
+            ),
+        ));
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            my_formatter:
+                class: Symfony\Bridge\Monolog\Formatter\ConsoleFormatter
+                arguments:
+                    - "[%%datetime%%] %%start_tag%%%%message%%%%end_tag%% (%%level_name%%) %%context%% %%extra%%\n"
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+             <services>
+                <service id="my_formatter" class="Symfony\Bridge\Monolog\Formatter\ConsoleFormatter">
+                    <argument>[%%datetime%%] %%start_tag%%%%message%%%%end_tag%% (%%level_name%%) %%context%% %%extra%%\n</argument>
+                </service>
+             </services>
+
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        $container
+            ->register('my_formatter', 'Symfony\Bridge\Monolog\Formatter\ConsoleFormatter')
+            ->addArgument('[%%datetime%%] %%start_tag%%%%message%%%%end_tag%% (%%level_name%%) %%context%% %%extra%%\n')
+        ;
+
+.. _ConsoleHandler: https://github.com/symfony/MonologBridge/blob/master/Handler/ConsoleHandler.php
+.. _MonologBundle: https://github.com/symfony/MonologBundle
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -101,6 +101,7 @@
 
   * :doc:`/cookbook/logging/monolog`
   * :doc:`/cookbook/logging/monolog_email`
+  * :doc:`/cookbook/logging/monolog_console`
   * :doc:`/cookbook/logging/monolog_regex_based_excludes`
   * :doc:`/cookbook/logging/channels_handlers`
 

diff --git a/reference/configuration/monolog.rst b/reference/configuration/monolog.rst
@@ -25,11 +25,18 @@ MonologBundle Configuration ("monolog")
                     action_level:        WARNING
                     buffer_size:         30
                     handler:             custom
+                console:
+                    type:                console
+                    verbosity_levels:
+                        VERBOSITY_NORMAL:       WARNING
+                        VERBOSITY_VERBOSE:      NOTICE
+                        VERBOSITY_VERY_VERBOSE: INFO
+                        VERBOSITY_DEBUG:        DEBUG
                 custom:
                     type:                service
                     id:                  my_handler
 
-                # Default options and values for some "my_custom_handler" 
+                # Default options and values for some "my_custom_handler"
                 # Note: many of these options are specific to the "type".
                 # For example, the "service" type doesn't use any options
                 # except id and channels
@@ -84,6 +91,10 @@ MonologBundle Configuration ("monolog")
                     action-level="warning"
                     handler="custom"
                 />
+                <monolog:handler
+                    name="console"
+                    type="console"
+                />
                 <monolog:handler
                     name="custom"
                     type="service"