Merge pull request #76 from sensiolabs/issue-51/console_commands

Split most of Console component introduction to guide articles

Author: weaverryan

components/console.rst

@@ -133,301 +133,7 @@ Commands have three lifecycle methods:
     This method is executed after ``interact()`` and ``initialize()``.
     It contains the logic you want the command to execute.
 
-.. _components-console-coloring:
 
-Coloring the Output
-~~~~~~~~~~~~~~~~~~~
-
-.. note::
-
-    By default, the Windows command console doesn't support output coloring. The
-    Console component disables output coloring for Windows systems, but if your
-    commands invoke other scripts which emit color sequences, they will be
-    wrongly displayed as raw escape characters. Install the `Cmder`_, `ConEmu`_, `ANSICON`_
-    or `Mintty`_ (used by default in GitBash and Cygwin) free applications
-    to add coloring support to your Windows command console.
-
-Whenever you output text, you can surround the text with tags to color its
-output. For example::
-
-    // green text
-    $output->writeln('<info>foo</info>');
-
-    // yellow text
-    $output->writeln('<comment>foo</comment>');
-
-    // black text on a cyan background
-    $output->writeln('<question>foo</question>');
-
-    // white text on a red background
-    $output->writeln('<error>foo</error>');
-
-The closing tag can be replaced by ``</>``, which revokes all formatting options
-established by the last opened tag.
-
-It is possible to define your own styles using the class
-:class:`Symfony\\Component\\Console\\Formatter\\OutputFormatterStyle`::
-
-    use Symfony\Component\Console\Formatter\OutputFormatterStyle;
-
-    // ...
-    $style = new OutputFormatterStyle('red', 'yellow', array('bold', 'blink'));
-    $output->getFormatter()->setStyle('fire', $style);
-    $output->writeln('<fire>foo</>');
-
-Available foreground and background colors are: ``black``, ``red``, ``green``,
-``yellow``, ``blue``, ``magenta``, ``cyan`` and ``white``.
-
-And available options are: ``bold``, ``underscore``, ``blink``, ``reverse``
-(enables the "reverse video" mode where the background and foreground colors
-are swapped) and ``conceal`` (sets the foreground color to transparent, making
-the typed text invisible - although it can be selected and copied; this option is
-commonly used when asking the user to type sensitive information).
-
-You can also set these colors and options inside the tagname::
-
-    // green text
-    $output->writeln('<fg=green>foo</>');
-
-    // black text on a cyan background
-    $output->writeln('<fg=black;bg=cyan>foo</>');
-
-    // bold text on a yellow background
-    $output->writeln('<bg=yellow;options=bold>foo</>');
-
-.. _verbosity-levels:
-
-Verbosity Levels
-~~~~~~~~~~~~~~~~
-
-.. versionadded:: 2.3
-   The ``VERBOSITY_VERY_VERBOSE`` and ``VERBOSITY_DEBUG`` constants were introduced
-   in version 2.3
-
-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``
-===========================================  ==================================  =====================
-
-.. tip::
-
-    The full exception stacktrace is printed if the ``VERBOSITY_VERBOSE``
-    level or above is used.
-
-It is possible to print a message in a command for only a specific verbosity
-level. For example::
-
-    if ($output->getVerbosity() >= OutputInterface::VERBOSITY_VERBOSE) {
-        $output->writeln(...);
-    }
-
-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 backwards 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.
-
-.. tip::
-
-    The MonologBridge provides a :class:`Symfony\\Bridge\\Monolog\\Handler\\ConsoleHandler`
-    class that allows you to display messages on the console. This is cleaner
-    than wrapping your output calls in conditions. For an example use in
-    the Symfony Framework, see :doc:`/logging/monolog_console`.
-
-Using Command Arguments
------------------------
-
-The most interesting part of the commands are the arguments and options that
-you can make available. Arguments are the strings - separated by spaces - that
-come after the command name itself. They are ordered, and can be optional
-or required. For example, add an optional ``last_name`` argument to the command
-and make the ``name`` argument required::
-
-    $this
-        // ...
-        ->addArgument(
-            'name',
-            InputArgument::REQUIRED,
-            'Who do you want to greet?'
-        )
-        ->addArgument(
-            'last_name',
-            InputArgument::OPTIONAL,
-            'Your last name?'
-        );
-
-You now have access to a ``last_name`` argument in your command::
-
-    if ($lastName = $input->getArgument('last_name')) {
-        $text .= ' '.$lastName;
-    }
-
-The command can now be used in either of the following ways:
-
-.. code-block:: bash
-
-    $ php application.php demo:greet Fabien
-    $ php application.php demo:greet Fabien Potencier
-
-It is also possible to let an argument take a list of values (imagine you want
-to greet all your friends). For this it must be specified at the end of the
-argument list::
-
-    $this
-        // ...
-        ->addArgument(
-            'names',
-            InputArgument::IS_ARRAY,
-            'Who do you want to greet (separate multiple names with a space)?'
-        );
-
-To use this, just specify as many names as you want:
-
-.. code-block:: bash
-
-    $ php application.php demo:greet Fabien Ryan Bernhard
-
-You can access the ``names`` argument as an array::
-
-    if ($names = $input->getArgument('names')) {
-        $text .= ' '.implode(', ', $names);
-    }
-
-There are three argument variants you can use:
-
-===========================  ===========================================================================================================
-Mode                         Value
-===========================  ===========================================================================================================
-``InputArgument::REQUIRED``  The argument is required
-``InputArgument::OPTIONAL``  The argument is optional and therefore can be omitted
-``InputArgument::IS_ARRAY``  The argument can contain an indefinite number of arguments and must be used at the end of the argument list
-===========================  ===========================================================================================================
-
-You can combine ``IS_ARRAY`` with ``REQUIRED`` and ``OPTIONAL`` like this::
-
-    $this
-        // ...
-        ->addArgument(
-            'names',
-            InputArgument::IS_ARRAY | InputArgument::REQUIRED,
-            'Who do you want to greet (separate multiple names with a space)?'
-        );
-
-Using Command Options
----------------------
-
-Unlike arguments, options are not ordered (meaning you can specify them in any
-order) and are specified with two dashes (e.g. ``--yell`` - you can also
-declare a one-letter shortcut that you can call with a single dash like
-``-y``). Options are *always* optional, and can be setup to accept a value
-(e.g. ``--dir=src``) or simply as a boolean flag without a value (e.g.
-``--yell``).
-
-.. tip::
-
-    There is nothing forbidding you to create a command with an option that
-    optionally accepts a value. However, there is no way you can distinguish
-    when the option was used without a value (``command --yell``) or when it
-    wasn't used at all (``command``). In both cases, the value retrieved for
-    the option will be ``null``.
-
-For example, add a new option to the command that can be used to specify
-how many times in a row the message should be printed::
-
-    $this
-        // ...
-        ->addOption(
-            'iterations',
-            null,
-            InputOption::VALUE_REQUIRED,
-            'How many times should the message be printed?',
-            1
-        );
-
-Next, use this in the command to print the message multiple times:
-
-.. code-block:: php
-
-    for ($i = 0; $i < $input->getOption('iterations'); $i++) {
-        $output->writeln($text);
-    }
-
-Now, when you run the task, you can optionally specify a ``--iterations``
-flag:
-
-.. code-block:: bash
-
-    $ php application.php demo:greet Fabien
-    $ php application.php demo:greet Fabien --iterations=5
-
-The first example will only print once, since ``iterations`` is empty and
-defaults to ``1`` (the last argument of ``addOption``). The second example
-will print five times.
-
-Recall that options don't care about their order. So, either of the following
-will work:
-
-.. code-block:: bash
-
-    $ php application.php demo:greet Fabien --iterations=5 --yell
-    $ php application.php demo:greet Fabien --yell --iterations=5
-
-There are 4 option variants you can use:
-
-===============================  =====================================================================================
-Option                           Value
-===============================  =====================================================================================
-``InputOption::VALUE_IS_ARRAY``  This option accepts multiple values (e.g. ``--dir=/foo --dir=/bar``)
-``InputOption::VALUE_NONE``      Do not accept input for this option (e.g. ``--yell``)
-``InputOption::VALUE_REQUIRED``  This value is required (e.g. ``--iterations=5``), the option itself is still optional
-``InputOption::VALUE_OPTIONAL``  This option may or may not have a value (e.g. ``--yell`` or ``--yell=loud``)
-===============================  =====================================================================================
-
-You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or ``VALUE_OPTIONAL`` like this:
-
-.. code-block:: php
-
-    $this
-        // ...
-        ->addOption(
-            'colors',
-            null,
-            InputOption::VALUE_REQUIRED | InputOption::VALUE_IS_ARRAY,
-            'Which colors do you like?',
-            array('blue', 'red')
-        );
 
 Console Helpers
 ---------------

components/console/helpers/debug_formatter.rst

@@ -36,7 +36,7 @@ multiple programs at the same time. When using the
 .. tip::
 
     This information is often too verbose to be shown by default. You can use
-    :ref:`verbosity levels <verbosity-levels>` to only show it when in
+    :doc:`verbosity levels </console/verbosity>` to only show it when in
     debugging mode (``-vvv``).
 
 Starting a Program

components/console/helpers/formatterhelper.rst

@@ -6,7 +6,7 @@ Formatter Helper
 
 The Formatter helpers provides functions to format the output with colors.
 You can do more advanced things with this helper than you can in
-:ref:`components-console-coloring`.
+:doc:`/console/coloring`.
 
 The :class:`Symfony\\Component\\Console\\Helper\\FormatterHelper` is included
 in the default helper set, which you can get by calling

console/coloring.rst

@@ -0,0 +1,66 @@
+How to Color and Style the Console Output
+=========================================
+
+By using colors in the command output, you can distinguish different types of
+output (e.g. important messages, titles, comments, etc.).
+
+.. note::
+
+    By default, the Windows command console doesn't support output coloring. The
+    Console component disables output coloring for Windows systems, but if your
+    commands invoke other scripts which emit color sequences, they will be
+    wrongly displayed as raw escape characters. Install the `Cmder`_, `ConEmu`_, `ANSICON`_
+    or `Mintty`_ (used by default in GitBash and Cygwin) free applications
+    to add coloring support to your Windows command console.
+
+Using Color Styles
+------------------
+
+Whenever you output text, you can surround the text with tags to color its
+output. For example::
+
+    // green text
+    $output->writeln('<info>foo</info>');
+
+    // yellow text
+    $output->writeln('<comment>foo</comment>');
+
+    // black text on a cyan background
+    $output->writeln('<question>foo</question>');
+
+    // white text on a red background
+    $output->writeln('<error>foo</error>');
+
+The closing tag can be replaced by ``</>``, which revokes all formatting options
+established by the last opened tag.
+
+It is possible to define your own styles using the
+:class:`Symfony\\Component\\Console\\Formatter\\OutputFormatterStyle` class::
+
+    use Symfony\Component\Console\Formatter\OutputFormatterStyle;
+
+    // ...
+    $style = new OutputFormatterStyle('red', 'yellow', array('bold', 'blink'));
+    $output->getFormatter()->setStyle('fire', $style);
+
+    $output->writeln('<fire>foo</fire>');
+
+Available foreground and background colors are: ``black``, ``red``, ``green``,
+``yellow``, ``blue``, ``magenta``, ``cyan`` and ``white``.
+
+And available options are: ``bold``, ``underscore``, ``blink``, ``reverse``
+(enables the "reverse video" mode where the background and foreground colors
+are swapped) and ``conceal`` (sets the foreground color to transparent, making
+the typed text invisible - although it can be selected and copied; this option is
+commonly used when asking the user to type sensitive information).
+
+You can also set these colors and options directly inside the tagname::
+
+    // green text
+    $output->writeln('<fg=green>foo</>');
+
+    // black text on a cyan background
+    $output->writeln('<fg=black;bg=cyan>foo</>');
+
+    // bold text on a yellow background
+    $output->writeln('<bg=yellow;options=bold>foo</>');