merged branch Tobion/console-nulloutput (PR #8037)

This PR was merged into the master branch.

Discussion
----------

[Console] fix Output classes

Please see commits.

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| License       | MIT

Commits
-------

940b788 [Console] use inheritdoc for Output classes
bd61b92 [Console] fix phpdoc of Output classes (esp. regarding the new verbosities)
9dcc9fa [Console] fix abstract Output class that fasly claims to support guessing of decorated variable.
2628d88 [Console] the default type value should use the constant in OutputInterface::write
ee0cc40 [Console] fix NullOutput
a290f87 [Console] fix test for NullOutput that does not print anything and add a failing test for verbosity

src/Symfony/Component/Console/Output/ConsoleOutput.php

@@ -36,10 +36,9 @@ class ConsoleOutput extends StreamOutput implements ConsoleOutputInterface
     /**
      * Constructor.
      *
-     * @param integer                  $verbosity The verbosity level (self::VERBOSITY_QUIET, self::VERBOSITY_NORMAL,
+     * @param integer                       $verbosity The verbosity level (one of the VERBOSITY constants in OutputInterface)
-     *                                                                 self::VERBOSITY_VERBOSE)
+     * @param Boolean|null                  $decorated Whether to decorate messages (null for auto-guessing)
-     * @param Boolean                  $decorated Whether to decorate messages or not (null for auto-guessing)
+     * @param OutputFormatterInterface|null $formatter Output formatter instance (null to use default OutputFormatter)
-     * @param OutputFormatterInterface $formatter Output formatter instance
      *
      * @api
      */
@@ -55,18 +54,27 @@ class ConsoleOutput extends StreamOutput implements ConsoleOutputInterface
         $this->stderr = new StreamOutput(fopen('php://stderr', 'w'), $verbosity, $decorated, $formatter);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setDecorated($decorated)
     {
         parent::setDecorated($decorated);
         $this->stderr->setDecorated($decorated);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setFormatter(OutputFormatterInterface $formatter)
     {
         parent::setFormatter($formatter);
         $this->stderr->setFormatter($formatter);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setVerbosity($level)
     {
         parent::setVerbosity($level);
@@ -74,13 +82,16 @@ class ConsoleOutput extends StreamOutput implements ConsoleOutputInterface
     }
 
     /**
-     * @return OutputInterface
+     * {@inheritdoc}
      */
     public function getErrorOutput()
     {
         return $this->stderr;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setErrorOutput(OutputInterface $error)
     {
         $this->stderr = $error;

src/Symfony/Component/Console/Output/ConsoleOutputInterface.php

@@ -22,9 +22,16 @@ use Symfony\Component\Console\Output\OutputInterface;
 interface ConsoleOutputInterface extends OutputInterface
 {
     /**
+     * Gets the OutputInterface for errors.
+     *
      * @return OutputInterface
      */
     public function getErrorOutput();
 
+    /**
+     * Sets the OutputInterface used for errors.
+     *
+     * @param OutputInterface $error
+     */
     public function setErrorOutput(OutputInterface $error);
 }

src/Symfony/Component/Console/Output/NullOutput.php

@@ -11,24 +11,83 @@
 
 namespace Symfony\Component\Console\Output;
 
+use Symfony\Component\Console\Formatter\OutputFormatter;
+use Symfony\Component\Console\Formatter\OutputFormatterInterface;
+
 /**
  * NullOutput suppresses all output.
  *
  *     $output = new NullOutput();
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ * @author Tobias Schultze <http://tobion.de>
  *
  * @api
  */
-class NullOutput extends Output
+class NullOutput implements OutputInterface
 {
     /**
-     * Writes a message to the output.
+     * {@inheritdoc}
-     *
-     * @param string  $message A message to write to the output
-     * @param Boolean $newline Whether to add a newline or not
      */
-    protected function doWrite($message, $newline)
+    public function setFormatter(OutputFormatterInterface $formatter)
     {
+        // do nothing
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getFormatter()
+    {
+        // to comply with the interface we must return a OutputFormatterInterface
+        return new OutputFormatter();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setDecorated($decorated)
+    {
+        // do nothing
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function isDecorated()
+    {
+        return false;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setVerbosity($level)
+    {
+        // do nothing
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getVerbosity()
+    {
+        return self::VERBOSITY_QUIET;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function writeln($messages, $type = self::OUTPUT_NORMAL)
+    {
+        // do nothing
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function write($messages, $newline = false, $type = self::OUTPUT_NORMAL)
+    {
+        // do nothing
     }
 }

src/Symfony/Component/Console/Output/Output.php

@@ -17,10 +17,12 @@ use Symfony\Component\Console\Formatter\OutputFormatter;
 /**
  * Base class for output classes.
  *
- * There are three levels of verbosity:
+ * There are five levels of verbosity:
  *
- *  * normal: no option passed (normal output - information)
+ *  * normal: no option passed (normal output)
- *  * verbose: -v (more output - debug)
+ *  * verbose: -v (more output)
+ *  * very verbose: -vv (highly extended output)
+ *  * debug: -vvv (all debug output)
  *  * quiet: -q (no output)
  *
  * @author Fabien Potencier <fabien@symfony.com>
@@ -35,25 +37,21 @@ abstract class Output implements OutputInterface
     /**
      * Constructor.
      *
-     * @param integer                  $verbosity The verbosity level (self::VERBOSITY_QUIET, self::VERBOSITY_NORMAL, self::VERBOSITY_VERBOSE)
+     * @param integer                       $verbosity The verbosity level (one of the VERBOSITY constants in OutputInterface)
-     * @param Boolean                  $decorated Whether to decorate messages or not (null for auto-guessing)
+     * @param Boolean                       $decorated Whether to decorate messages
-     * @param OutputFormatterInterface $formatter Output formatter instance
+     * @param OutputFormatterInterface|null $formatter Output formatter instance (null to use default OutputFormatter)
      *
      * @api
      */
-    public function __construct($verbosity = self::VERBOSITY_NORMAL, $decorated = null, OutputFormatterInterface $formatter = null)
+    public function __construct($verbosity = self::VERBOSITY_NORMAL, $decorated = false, OutputFormatterInterface $formatter = null)
     {
         $this->verbosity = null === $verbosity ? self::VERBOSITY_NORMAL : $verbosity;
         $this->formatter = null === $formatter ? new OutputFormatter() : $formatter;
-        $this->formatter->setDecorated((Boolean) $decorated);
+        $this->formatter->setDecorated($decorated);
     }
 
     /**
-     * Sets output formatter.
+     * {@inheritdoc}
-     *
-     * @param OutputFormatterInterface $formatter
-     *
-     * @api
      */
     public function setFormatter(OutputFormatterInterface $formatter)
     {
@@ -61,11 +59,7 @@ abstract class Output implements OutputInterface
     }
 
     /**
-     * Returns current output formatter instance.
+     * {@inheritdoc}
-     *
-     * @return  OutputFormatterInterface
-     *
-     * @api
      */
     public function getFormatter()
     {
@@ -73,23 +67,15 @@ abstract class Output implements OutputInterface
     }
 
     /**
-     * Sets the decorated flag.
+     * {@inheritdoc}
-     *
-     * @param Boolean $decorated Whether to decorate the messages or not
-     *
-     * @api
      */
     public function setDecorated($decorated)
     {
-        $this->formatter->setDecorated((Boolean) $decorated);
+        $this->formatter->setDecorated($decorated);
     }
 
     /**
-     * Gets the decorated flag.
+     * {@inheritdoc}
-     *
-     * @return Boolean true if the output will decorate messages, false otherwise
-     *
-     * @api
      */
     public function isDecorated()
     {
@@ -97,11 +83,7 @@ abstract class Output implements OutputInterface
     }
 
     /**
-     * Sets the verbosity of the output.
+     * {@inheritdoc}
-     *
-     * @param integer $level The level of verbosity
-     *
-     * @api
      */
     public function setVerbosity($level)
     {
@@ -109,11 +91,7 @@ abstract class Output implements OutputInterface
     }
 
     /**
-     * Gets the current verbosity of the output.
+     * {@inheritdoc}
-     *
-     * @return integer The current level of verbosity
-     *
-     * @api
      */
     public function getVerbosity()
     {
@@ -121,30 +99,17 @@ abstract class Output implements OutputInterface
     }
 
     /**
-     * Writes a message to the output and adds a newline at the end.
+     * {@inheritdoc}
-     *
-     * @param string|array $messages The message as an array of lines or a single string
-     * @param integer      $type     The type of output
-     *
-     * @api
      */
-    public function writeln($messages, $type = 0)
+    public function writeln($messages, $type = self::OUTPUT_NORMAL)
     {
         $this->write($messages, true, $type);
     }
 
     /**
-     * Writes a message to the output.
+     * {@inheritdoc}
-     *
-     * @param string|array $messages The message as an array of lines or a single string
-     * @param Boolean      $newline  Whether to add a newline or not
-     * @param integer      $type     The type of output
-     *
-     * @throws \InvalidArgumentException When unknown output type is given
-     *
-     * @api
      */
-    public function write($messages, $newline = false, $type = 0)
+    public function write($messages, $newline = false, $type = self::OUTPUT_NORMAL)
     {
         if (self::VERBOSITY_QUIET === $this->verbosity) {
             return;

src/Symfony/Component/Console/Output/OutputInterface.php

@@ -36,29 +36,31 @@ interface OutputInterface
      * Writes a message to the output.
      *
      * @param string|array $messages The message as an array of lines or a single string
-     * @param Boolean      $newline  Whether to add a newline or not
+     * @param Boolean      $newline  Whether to add a newline
-     * @param integer      $type     The type of output (0: normal, 1: raw, 2: plain)
+     * @param integer      $type     The type of output (one of the OUTPUT constants)
      *
      * @throws \InvalidArgumentException When unknown output type is given
      *
      * @api
      */
-    public function write($messages, $newline = false, $type = 0);
+    public function write($messages, $newline = false, $type = self::OUTPUT_NORMAL);
 
     /**
      * Writes a message to the output and adds a newline at the end.
      *
      * @param string|array $messages The message as an array of lines of a single string
-     * @param integer      $type     The type of output (0: normal, 1: raw, 2: plain)
+     * @param integer      $type     The type of output (one of the OUTPUT constants)
+     *
+     * @throws \InvalidArgumentException When unknown output type is given
      *
      * @api
      */
-    public function writeln($messages, $type = 0);
+    public function writeln($messages, $type = self::OUTPUT_NORMAL);
 
     /**
      * Sets the verbosity of the output.
      *
-     * @param integer $level The level of verbosity
+     * @param integer $level The level of verbosity (one of the VERBOSITY constants)
      *
      * @api
      */
@@ -67,7 +69,7 @@ interface OutputInterface
     /**
      * Gets the current verbosity of the output.
      *
-     * @return integer The current level of verbosity
+     * @return integer The current level of verbosity (one of the VERBOSITY constants)
      *
      * @api
      */
@@ -76,7 +78,7 @@ interface OutputInterface
     /**
      * Sets the decorated flag.
      *
-     * @param Boolean $decorated Whether to decorate the messages or not
+     * @param Boolean $decorated Whether to decorate the messages
      *
      * @api
      */

src/Symfony/Component/Console/Output/StreamOutput.php

@@ -35,11 +35,10 @@ class StreamOutput extends Output
     /**
      * Constructor.
      *
-     * @param mixed                    $stream    A stream resource
+     * @param mixed                         $stream    A stream resource
-     * @param integer                  $verbosity The verbosity level (self::VERBOSITY_QUIET, self::VERBOSITY_NORMAL,
+     * @param integer                       $verbosity The verbosity level (one of the VERBOSITY constants in OutputInterface)
-     *                                                                 self::VERBOSITY_VERBOSE)
+     * @param Boolean|null                  $decorated Whether to decorate messages (null for auto-guessing)
-     * @param Boolean                  $decorated Whether to decorate messages or not (null for auto-guessing)
+     * @param OutputFormatterInterface|null $formatter Output formatter instance (null to use default OutputFormatter)
-     * @param OutputFormatterInterface $formatter Output formatter instance
      *
      * @throws \InvalidArgumentException When first argument is not a real stream
      *
@@ -71,12 +70,7 @@ class StreamOutput extends Output
     }
 
     /**
-     * Writes a message to the output.
+     * {@inheritdoc}
-     *
-     * @param string  $message A message to write to the output
-     * @param Boolean $newline Whether to add a newline or not
-     *
-     * @throws \RuntimeException When unable to write output (should never happen)
      */
     protected function doWrite($message, $newline)
     {

src/Symfony/Component/Console/Tests/Output/NullOutputTest.php

@@ -12,13 +12,28 @@
 namespace Symfony\Component\Console\Tests\Output;
 
 use Symfony\Component\Console\Output\NullOutput;
+use Symfony\Component\Console\Output\OutputInterface;
 
 class NullOutputTest extends \PHPUnit_Framework_TestCase
 {
     public function testConstructor()
     {
         $output = new NullOutput();
+
+        ob_start();
         $output->write('foo');
-        $this->assertTrue(true, '->write() does nothing'); // FIXME
+        $buffer = ob_get_clean();
+
+        $this->assertSame('', $buffer, '->write() does nothing (at least nothing is printed)');
+        $this->assertFalse($output->isDecorated(), '->isDecorated() returns false');
+    }
+
+    public function testVerbosity()
+    {
+        $output = new NullOutput();
+        $this->assertSame(OutputInterface::VERBOSITY_QUIET, $output->getVerbosity(), '->getVerbosity() returns VERBOSITY_QUIET for NullOutput by default');
+
+        $output->setVerbosity(OutputInterface::VERBOSITY_VERBOSE);
+        $this->assertSame(OutputInterface::VERBOSITY_QUIET, $output->getVerbosity(), '->getVerbosity() always returns VERBOSITY_QUIET for NullOutput');
     }
 }