minor #8896 Reworded the console verbosity article to explain SHELL_VERBOSITY too (javiereguiluz)

javiereguiluz · javiereguiluz · commit 1a06394a050b · 2018-01-02T16:13:51.000+01:00
This PR was squashed before being merged into the 3.4 branch (closes #8896). Discussion ---------- Reworded the console verbosity article to explain SHELL_VERBOSITY too This fixes #8565. Commits ------- 98b2232 Reworded the console verbosity article to explain SHELL_VERBOSITY too
diff --git a/console/verbosity.rst b/console/verbosity.rst
@@ -1,18 +1,41 @@
 Verbosity Levels
 ================
 
-The console has five verbosity levels. These are defined in the
-:class:`Symfony\\Component\\Console\\Output\\OutputInterface`:
-
-===========================================  ==================================  =====================
-Value                                        Meaning                             Console option
-===========================================  ==================================  =====================
-``OutputInterface::VERBOSITY_QUIET``         Do not output any messages          ``-q`` or ``--quiet``
-``OutputInterface::VERBOSITY_NORMAL``        The default verbosity level         (none)
-``OutputInterface::VERBOSITY_VERBOSE``       Increased verbosity of messages     ``-v``
-``OutputInterface::VERBOSITY_VERY_VERBOSE``  Informative non essential messages  ``-vv``
-``OutputInterface::VERBOSITY_DEBUG``         Debug messages                      ``-vvv``
-===========================================  ==================================  =====================
+Console commands have different verbosity levels, which determine the messages
+displayed in their output. By default, commands display only the most useful
+messages, but you can control their verbosity with the ``-q`` and ``-v`` options:
+
+.. code-block:: terminal
+
+    # do not output any message (not even the command result messages)
+    $ php bin/console some-command -q
+    $ php bin/console some-command --quiet
+
+    # normal behavior, no option required (display only the useful messages)
+    $ php bin/console some-command
+
+    # increase verbosity of messages
+    $ php bin/console some-command -v
+
+    # display also the informative non essential messages
+    $ php bin/console some-command -vv
+
+    # display all messages (useful to debug errors)
+    $ php bin/console some-command -vvv
+
+The verbosity level can also be controlled globally for all commands with the
+``SHELL_VERBOSITY`` environment variable (the ``-q`` and ``-v`` options still
+have more precedence over the value of ``SHELL_VERBOSITY``):
+
+=====================  =========================  ===========================================
+Console option         ``SHELL_VERBOSITY`` value  Equivalent PHP constant
+=====================  =========================  ===========================================
+``-q`` or ``--quiet``  ``-1``                     ``OutputInterface::VERBOSITY_QUIET``
+(none)                 ``0``                      ``OutputInterface::VERBOSITY_NORMAL``
+``-v``                 ``1``                      ``OutputInterface::VERBOSITY_VERBOSE``
+``-vv``                ``2``                      ``OutputInterface::VERBOSITY_VERY_VERBOSE``
+``-vvv``               ``3``                      ``OutputInterface::VERBOSITY_DEBUG``
+=====================  =========================  ===========================================
 
 It is possible to print a message in a command for only a specific verbosity
 level. For example::
@@ -31,45 +54,19 @@ level. For example::
                 'Password: '.$input->getArgument('password'),
             ));
 
-            // the user class is only printed when the verbose verbosity level is used
-            if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
+            // available methods: ->isQuiet(), ->isVerbose(), ->isVeryVerbose(), ->isDebug()
+            if ($output->isVerbose()) {
                 $output->writeln('User class: '.get_class($user));
             }
 
-            // alternatively you can pass the verbosity level to writeln()
+            // alternatively you can pass the verbosity level PHP constant to writeln()
             $output->writeln(
                 'Will only be printed in verbose mode or higher',
                 OutputInterface::VERBOSITY_VERBOSE
             );
         }
     }
 
-There are also more semantic methods you can use to test for each of the
-verbosity levels::
-
-    if ($output->isQuiet()) {
-        // ...
-    }
-
-    if ($output->isVerbose()) {
-        // ...
-    }
-
-    if ($output->isVeryVerbose()) {
-        // ...
-    }
-
-    if ($output->isDebug()) {
-        // ...
-    }
-
-.. note::
-
-    These semantic methods are defined in the ``OutputInterface`` starting from
-    Symfony 3.0. In previous Symfony versions they are defined in the different
-    implementations of the interface (e.g. :class:`Symfony\\Component\\Console\\Output\\Output`)
-    in order to keep backward compatibility.
-
 When the quiet level is used, all output is suppressed as the default
 :method:`Symfony\\Component\\Console\\Output\\Output::write` method returns
 without actually printing.
