feature #3626 added documentation for the new Symfony 2.5 progress ba…

…r (fabpot)

This PR was merged into the master branch.

Discussion
----------

added documentation for the new Symfony 2.5 progress bar

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#10356)
| Applies to    | 2.5+
| Fixed tickets | n/a

Commits
-------

9e2727d added documentation for the new Symfony 2.5 progress bar

components/console/helpers/index.rst

@@ -9,6 +9,7 @@ The Console Helpers
 
     dialoghelper
     formatterhelper
+    progressbar
     progresshelper
     tablehelper
 

components/console/helpers/map.rst.inc

@@ -1,4 +1,5 @@
 * :doc:`/components/console/helpers/dialoghelper`
 * :doc:`/components/console/helpers/formatterhelper`
+* :doc:`/components/console/helpers/progressbar`
 * :doc:`/components/console/helpers/progresshelper`
 * :doc:`/components/console/helpers/tablehelper`

components/console/helpers/progressbar.rst

@@ -0,0 +1,322 @@
+.. index::
+    single: Console Helpers; Progress Bar
+
+Progress Bar
+============
+
+.. versionadded:: 2.5
+    The Progress Bar feature was introduced in Symfony 2.5 as a replacement for
+    the :doc:`Progress Helper </components/console/helpers/progresshelper>`.
+
+When executing longer-running commands, it may be helpful to show progress
+information, which updates as your command runs:
+
+.. image:: /images/components/console/progressbar.gif
+
+To display progress details, use the
+:class:`Symfony\\Component\\Console\\Helper\\ProgressBar`, pass it a total
+number of units, and advance the progress as the command executes::
+
+    use Symfony\Component\Console\Helper\ProgressBar;
+
+    // create a new progress bar (50 units)
+    $progress = new ProgressBar($output, 50);
+
+    // start and displays the progress bar
+    $progress->start();
+
+    $i = 0;
+    while ($i++ < 50) {
+        // ... do some work
+
+        // advance the progress bar 1 unit
+        $progress->advance();
+
+        // you can also advance the progress bar by more than 1 unit
+        // $progress->advance(3);
+    }
+
+    // ensure that the progress bar is at 100%
+    $progress->finish();
+
+Instead of advancing the bar by a number of steps (with the
+:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::advance` method),
+you can also set the current progress by calling the
+:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::setCurrent` method.
+
+.. caution::
+
+    The progress bar only works if your platform supports ANSI codes; on other
+    platforms, no output is generated.
+
+If you don't know the number of steps in advance, just omit the steps argument
+when creating the :class:`Symfony\\Component\\Console\\Helper\\ProgressBar`
+instance::
+
+    $progress = new ProgressBar($output);
+
+The progress will then be displayed as a throbber::
+
+.. code-block:: text
+
+    # no max steps (displays it like a throbber)
+        0 [>---------------------------]
+        5 [----->----------------------]
+        5 [============================]
+
+    # max steps defined
+     0/3 [>---------------------------]   0%
+     1/3 [=========>------------------]  33%
+     3/3 [============================] 100%
+
+Whenever your task is finished, don't forget to call
+:method:`Symfony\\Component\\Console\\Helper\\ProgressBar::finish` to ensure
+that the progress bar display is refreshed with a 100% completion.
+
+.. note::
+
+    If you want to output something while the progress bar is running,
+    call :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::clear` first.
+    After you're done, call
+    :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::display`
+    to show the progress bar again.
+
+Customizing the Progress Bar
+----------------------------
+
+Built-in Formats
+~~~~~~~~~~~~~~~~
+
+By default, the information rendered on a progress bar depends on the current
+level of verbosity of the ``OutputInterface`` instance:
+
+.. code-block:: text
+
+    # OutputInterface::VERBOSITY_NORMAL (CLI with no verbosity flag)
+     0/3 [>---------------------------]   0%
+     1/3 [=========>------------------]  33%
+     3/3 [============================] 100%
+
+    # OutputInterface::VERBOSITY_VERBOSE (-v)
+     0/3 [>---------------------------]   0%  1 sec
+     1/3 [=========>------------------]  33%  1 sec
+     3/3 [============================] 100%  1 sec
+
+    # OutputInterface::VERBOSITY_VERY_VERBOSE (-vv)
+     0/3 [>---------------------------]   0%  1 sec
+     1/3 [=========>------------------]  33%  1 sec
+     3/3 [============================] 100%  1 sec
+
+    # OutputInterface::VERBOSITY_DEBUG (-vvv)
+     0/3 [>---------------------------]   0%  1 sec/1 sec  1.0 MB
+     1/3 [=========>------------------]  33%  1 sec/1 sec  1.0 MB
+     3/3 [============================] 100%  1 sec/1 sec  1.0 MB
+
+.. note::
+
+    If you call a command with the quiet flag (``-q``), the progress bar won't
+    be displayed.
+
+Instead of relying on the verbosity mode of the current command, you can also
+force a format via ``setFormat()``::
+
+    $bar->setFormat('verbose');
+
+The built-in formats are the following:
+
+* ``normal``
+* ``verbose``
+* ``very_verbose``
+* ``debug``
+
+If you don't set the number of steps for your progress bar, use the ``_nomax``
+variants:
+
+* ``normal_nomax``
+* ``verbose_nomax``
+* ``very_verbose_nomax``
+* ``debug_nomax``
+
+Custom Formats
+~~~~~~~~~~~~~~
+
+Instead of using the built-in formats, you can also set your own::
+
+    $bar->setFormat('%bar%');
+
+This sets the format to only display the progress bar itself:
+
+.. code-block:: text
+
+    >---------------------------
+    =========>------------------
+    ============================
+
+A progress bar format is a string that contains specific placeholders (a name
+enclosed with the ``%`` character); the placeholders are replaced based on the
+current progress of the bar. Here is a list of the built-in placeholders:
+
+* ``current``: The current step;
+* ``max``: The maximum number of steps (or 0 if no max is defined);
+* ``bar``: The bar itself;
+* ``percent``: The percentage of completion (not available if no max is defined);
+* ``elapsed``: The time elapsed since the start of the progress bar;
+* ``remaining``: The remaining time to complete the task (not available if no max is defined);
+* ``estimated``: The estimated time to complete the task (not available if no max is defined);
+* ``memory``: The current memory usage;
+* ``message``: The current message attached to the progress bar.
+
+For instance, here is how you could set the format to be the same as the
+``debug`` one::
+
+    $bar->setFormat(' %current%/%max% [%bar%] %percent:3s%% %elapsed:6s%/%estimated:-6s% %memory:6s%');
+
+Notice the ``:6s`` part added to some placeholders? That's how you can tweak
+the appearance of the bar (formatting and alignment). The part after the colon
+(``:``) is used to set the ``sprintf`` format of the string.
+
+The ``message`` placeholder is a bit special as you must set the value
+yourself::
+
+    $bar->setMessage('Task starts');
+    $bar->start();
+
+    $bar->setMessage('Task in progress...');
+    $bar->advance();
+
+    // ...
+
+    $bar->setMessage('Task is finished');
+    $bar->finish();
+
+Instead of setting the format for a given instance of a progress bar, you can
+also define global formats::
+
+    ProgressBar::setFormatDefinition('minimal', 'Progress: %percent%%');
+
+    $bar = new ProgressBar($output, 3);
+    $bar->setFormat('minimal');
+
+This code defines a new ``minimal`` format that you can then use for your
+progress bars:
+
+.. code-block:: text
+
+    Progress: 0%
+    Progress: 33%
+    Progress: 100%
+
+.. tip::
+
+    It is almost always better to redefine built-in formats instead of creating
+    new ones as that allows the display to automatically vary based on the
+    verbosity flag of the command.
+
+When defining a new style that contains placeholders that are only available
+when the maximum number of steps is known, you should create a ``_nomax``
+variant::
+
+    ProgressBar::setFormatDefinition('minimal', '%percent%% %remaining%');
+    ProgressBar::setFormatDefinition('minimal_nomax', '%percent%%');
+
+    $bar = new ProgressBar($output);
+    $bar->setFormat('minimal');
+
+When displaying the progress bar, the format will automatically be set to
+``minimal_nomax`` if the bar does not have a maximum number of steps like in
+the example above.
+
+.. tip::
+
+    A format can contain any valid ANSI codes and can also use the
+    Symfony-specific way to set colors::
+
+        ProgressBar::setFormatDefinition(
+            'minimal',
+            '<info>%percent%</info>\033[32m%\033[0m <fg=white;bg=blue>%remaining%</>'
+        );
+
+.. note::
+
+    A format can span more than one line; that's very useful when you want to
+    display more contextual information alongside the progress bar (see the
+    example at the beginning of this article).
+
+Bar Settings
+~~~~~~~~~~~~
+
+Amongst the placeholders, ``bar`` is a bit special as all the characters used
+to display it can be customized::
+
+    // the finished part of the bar
+    $progress->setBarCharacter('<comment>=</comment>');
+
+    // the unfinished part of the bar
+    $progress->setEmptyBarCharacter(' ');
+
+    // the progress character
+    $progress->setProgressCharacter('|');
+
+    // the bar width
+    $progress->setBarWidth(50);
+
+.. caution::
+
+    For performance reasons, be careful if you set the total number of steps
+    to a high number. For example, if you're iterating over a large number of
+    items, consider setting the redraw frequency to a higher value by calling
+    :method:`Symfony\\Component\\Console\\Helper\\ProgressHelper::setRedrawFrequency`,
+    so it updates on only some iterations::
+
+        $progress->start($output, 50000);
+
+        // update every 100 iterations
+        $progress->setRedrawFrequency(100);
+
+        $i = 0;
+        while ($i++ < 50000) {
+            // ... do some work
+
+            $progress->advance();
+        }
+
+Custom Placeholders
+~~~~~~~~~~~~~~~~~~~
+
+If you want to display some information that depends on the progress bar
+display that are not available in the list of built-in placeholders, you can
+create your own. Let's see how you can create a ``remaining_steps`` placeholder
+that displays the number of remaining steps::
+
+    ProgressBar::setPlaceholderFormatter(
+        '%remaining_steps%',
+        function (ProgressBar $bar, OutputInterface $output) {
+            return $bar->getMaxSteps() - $bar->getStep();
+        }
+    );
+
+Custom Messages
+~~~~~~~~~~~~~~~
+
+The ``%message%`` placeholder allows you to specify a custom message to be
+displayed with the progress bar. But if you need more than one, just define
+your own::
+
+    $bar->setMessage('Task starts');
+    $bar->setMessage('', 'filename');
+    $bar->start();
+
+    $bar->setMessage('Task is in progress...');
+    while ($file = array_pop($files)) {
+        $bar->setMessage($filename, 'filename');
+        $bar->advance();
+    }
+
+    $bar->setMessage('Task is finished');
+    $bar->setMessage('', 'filename');
+    $bar->finish();
+
+For the ``filename`` to be part of the progress bar, just add the
+``%filename%`` placeholder in your format::
+
+    $bar->setFormat(" %message%\n %step%/%max%\n Working on %filename%");

components/console/helpers/progresshelper.rst

@@ -10,6 +10,13 @@ Progress Helper
 .. versionadded:: 2.4
     The ``clear`` method was added in Symfony 2.4.
 
+.. caution::
+
+    The Progress Helper was deprecated in Symfony 2.5 and will be removed in
+    Symfony 3.0. You should now use the
+    :doc:`Progress Bar </components/console/helpers/progressbar>` instead which
+    is more powerful.
+
 When executing longer-running commands, it may be helpful to show progress
 information, which updates as your command runs:
 
@@ -25,7 +32,7 @@ pass it a total number of units, and advance the progress as your command execut
     while ($i++ < 50) {
         // ... do some work
 
-        // advance the progress bar 1 unit
+        // advances the progress bar 1 unit
         $progress->advance();
     }
 
@@ -79,7 +86,7 @@ To see other available options, check the API documentation for
 
         $progress->start($output, 50000);
 
-        // update every 100 iterations
+        // updates every 100 iterations
         $progress->setRedrawFrequency(100);
 
         $i = 0;