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:

# 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

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:

>---------------------------
=========>------------------
============================

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:

Progress: 0%
Progress: 33%
Progress: 100%

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.

ProgressBar::setFormatDefinition(
    'minimal',
    '<info>%percent%</info>\033[32m%\033[0m <fg=white;bg=blue>%remaining%</>'
);

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

$progress = new ProgressBar($output, 50000);
$progress->start();

// 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::setPlaceholderFormatterDefinition(
    'remaining_steps',
    function (ProgressBar $bar, OutputInterface $output) {
        return $bar->getMaxSteps() - $bar->getProgress();
    }
);

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%");