Skip to content

Latest commit

 

History

History
93 lines (68 loc) · 3.04 KB

progresshelper.rst

File metadata and controls

93 lines (68 loc) · 3.04 KB
.. index::
    single: Console Helpers; Progress Helper

Progress Helper

.. versionadded:: 2.2
    The ``progress`` helper was added in Symfony 2.2.


.. versionadded:: 2.3
    The ``setCurrent`` method was added in Symfony 2.3.


.. versionadded:: 2.4
    The ``clear`` method was added in Symfony 2.4.

When executing longer-running commands, it may be helpful to show progress information, which updates as your command runs:

/images/components/console/progress.png

To display progress details, use the :class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`, pass it a total number of units, and advance the progress as your command executes:

$progress = $this->getHelperSet()->get('progress');

$progress->start($output, 50);
$i = 0;
while ($i++ < 50) {
    // ... do some work

    // advance the progress bar 1 unit
    $progress->advance();
}

$progress->finish();

Tip

You can also set the current progress by calling the :method:`Symfony\\Component\\Console\\Helper\\ProgressHelper::setCurrent` method.

If you want to output something while the progress bar is running, call :method:`Symfony\\Component\\Console\\Helper\\ProgressHelper::clear` first. After you're done, call :method:`Symfony\\Component\\Console\\Helper\\ProgressHelper::display` to show the progress bar again.

The appearance of the progress output can be customized as well, with a number of different levels of verbosity. Each of these displays different possible items - like percentage completion, a moving progress bar, or current/total information (e.g. 10/50):

$progress->setFormat(ProgressHelper::FORMAT_QUIET);
$progress->setFormat(ProgressHelper::FORMAT_NORMAL);
$progress->setFormat(ProgressHelper::FORMAT_VERBOSE);
$progress->setFormat(ProgressHelper::FORMAT_QUIET_NOMAX);
// the default value
$progress->setFormat(ProgressHelper::FORMAT_NORMAL_NOMAX);
$progress->setFormat(ProgressHelper::FORMAT_VERBOSE_NOMAX);

You can also control the different characters and the width used for the progress bar:

// the finished part of the bar
$progress->setBarCharacter('<comment>=</comment>');
// the unfinished part of the bar
$progress->setEmptyBarCharacter(' ');
$progress->setProgressCharacter('|');
$progress->setBarWidth(50);

To see other available options, check the API documentation for :class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`.

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();
}