From 15628e64971b776cfdc3c3113ac619e4b4a16058 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= <dunglas@gmail.com>
Date: Wed, 19 Mar 2014 16:00:26 +0100
Subject: [PATCH] [Console] Added standalone PSR-3 compliant logger

---
 components/console/index.rst         |   1 +
 components/console/logger.rst        | 108 +++++++++++++++++++++++++++
 cookbook/logging/monolog_console.rst |   5 ++
 3 files changed, 114 insertions(+)
 create mode 100644 components/console/logger.rst

diff --git a/components/console/index.rst b/components/console/index.rst
index f974291a8e0..b449eff094b 100644
--- a/components/console/index.rst
+++ b/components/console/index.rst
@@ -9,4 +9,5 @@ Console
     changing_default_command
     single_command_tool
     events
+    logger
     helpers/index
diff --git a/components/console/logger.rst b/components/console/logger.rst
new file mode 100644
index 00000000000..84a41ad2b6c
--- /dev/null
+++ b/components/console/logger.rst
@@ -0,0 +1,108 @@
+.. index::
+    single: Console; Logger
+
+Using the Logger
+================
+
+.. versionadded:: 2.5
+    The :class:`Symfony\\Component\\Console\\Logger\\ConsoleLogger` was
+    introduced in Symfony 2.5.
+
+The Console component comes with a standalone logger complying with the
+`PSR-3_` standard.
+Depending of the verbosity setting, log messages will be sent to the
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface` instance
+passed as a parameter to the constructor.
+
+The logger does not have any external dependency except ``php-fig/log``.
+This is useful for console applications and commands needing a lightweight
+PSR-3 compliant logger::
+
+    namespace Acme;
+
+    use Psr\Log\LoggerInterface;
+
+    class MyDependency
+    {
+        private $logger;
+
+        public function __construct(LoggerInterface $logger)
+        {
+            $this->logger = $logger;
+        }
+
+        public function doStuff()
+        {
+            $this->logger->info('I love Tony Vairelles\' hairdresser.');
+        }
+    }
+
+You can rely on the logger to use this dependency inside a command::
+
+    namespace Acme\Console\Command;
+
+    use Acme\MyDependency;
+    use Symfony\Component\Console\Command\Command;
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
+    use Symfony\Component\Console\Logger\ConsoleLogger;
+
+    class MyCommand extends Command
+    {
+        protected function configure()
+        {
+            $this
+                ->setName('my:command')
+                ->setDescription(
+                    'Use an external dependency requiring a PSR-3 logger'
+                )
+            ;
+        }
+
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+            $logger = new ConsoleLogger($output);
+
+            $myDependency = MyDependency($logger);
+            $myDependency->doStuff();
+        }
+    }
+
+The dependency will use the instance of
+``Symfony\\Component\\Console\\Logger\\ConsoleLogger`` as logger.
+Log messages emitted will be displayed on the console output.
+
+Verbosity
+---------
+
+Depending on the verbosity level that the command is run, messages may or
+may not be sent to the ``Symfony\\Component\\Console\\Output\\OutputInterface`` instance.
+
+By default, the console logger behaves like the
+:doc:`Monolog's Console Handler </cookbook/logging/monolog_console>`.
+The association between the log level and the verbosity can be configured
+through the second parameter of the :class:`Symfony\\Component\\Console\\ConsoleLogger`
+constructor::
+
+    // ...
+    $verbosityLevelMap = array(
+        LogLevel::NOTICE => OutputInterface::VERBOSITY_NORMAL,
+        LogLevel::INFO   => OutputInterface::VERBOSITY_NORMAL,
+    );
+    $logger = new ConsoleLogger($output, $verbosityLevelMap);
+
+Color
+-----
+
+The logger outputs the log messages formatted with a color reflecting their
+level. This behavior is configurable through the third parameter of the
+constructor::
+
+    // ...
+    private $formatLevelMap = array(
+        LogLevel::CRITICAL => self::INFO,
+        LogLevel::DEBUG    => self::ERROR,
+    );
+    $logger = new ConsoleLogger($output, array(), $formatLevelMap);
+
+.. _PSR-3: http://www.php-fig.org/psr/psr-3/
\ No newline at end of file
diff --git a/cookbook/logging/monolog_console.rst b/cookbook/logging/monolog_console.rst
index 7945193022e..ec72197c4c9 100644
--- a/cookbook/logging/monolog_console.rst
+++ b/cookbook/logging/monolog_console.rst
@@ -12,6 +12,11 @@ It is possible to use the console to print messages for certain
 :class:`Symfony\\Component\\Console\\Output\\OutputInterface` instance that
 is passed when a command gets executed.
 
+.. seealso::
+    Alternatively, you can use the
+    :doc:`standalone PSR-3 logger </components/console/logger>` provided with
+    the console component.
+
 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.