feature #3696 [Console] Added standalone PSR-3 compliant logger (dung…

…las)

This PR was merged into the master branch.

Discussion
----------

[Console] Added standalone PSR-3 compliant logger

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes symfony/symfony#10194
| Applies to    | 2.5

Commits
-------

15628e6 [Console] Added standalone PSR-3 compliant logger

components/console/index.rst

@@ -9,4 +9,5 @@ Console
     changing_default_command
     single_command_tool
     events
+    logger
     helpers/index

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/

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.