Built-in Formats

By default, the information rendered on a progress bar depends on the current level of verbosity of the OutputInterface instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 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():

1

$progressBar->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:

1

$progressBar->setFormat('%bar%');

This sets the format to only display the progress bar itself:

1
2
3

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

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: used to display arbitrary messages in the progress bar (as explained later).

For instance, here is how you could set the format to be the same as the debug one:

1

$progressBar->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.

Instead of setting the format for a given instance of a progress bar, you can also define global formats:

1
2
3
4

ProgressBar::setFormatDefinition('minimal', 'Progress: %percent%%');

$progressBar = new ProgressBar($output, 3);
$progressBar->setFormat('minimal');

This code defines a new minimal format that you can then use for your progress bars:

1
2
3

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:

1
2
3
4
5

ProgressBar::setFormatDefinition('minimal', '%percent%% %remaining%');
ProgressBar::setFormatDefinition('minimal_nomax', '%percent%%');

$progressBar = new ProgressBar($output);
$progressBar->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.

1
2
3
4

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:

1
2
3
4
5
6
7
8
9
10
11

// the finished part of the bar
$progressBar->setBarCharacter('<comment>=</comment>');

// the unfinished part of the bar
$progressBar->setEmptyBarCharacter(' ');

// the progress character
$progressBar->setProgressCharacter('|');

// the bar width
$progressBar->setBarWidth(50);

1
2
3
4
5
6
7
8
9
10
11
12

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

// update every 100 iterations
$progressBar->setRedrawFrequency(100);

$i = 0;
while ($i++ < 50000) {
    // ... do some work

    $progressBar->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:

1
2
3
4
5
6

ProgressBar::setPlaceholderFormatterDefinition(
    'remaining_steps',
    function (ProgressBar $progressBar, OutputInterface $output) {
        return $progressBar->getMaxSteps() - $progressBar->getProgress();
    }
);

Custom Messages

Progress bars define a placeholder called message to display arbitrary messages. However, none of the built-in formats include that placeholder, so before displaying these messages, you must define your own custom format:

1
2
3
4

ProgressBar::setFormatDefinition('custom', ' %current%/%max% -- %message%');

$progressBar = new ProgressBar($output, 100);
$progressBar->setFormat('custom');

Now, use the setMessage() method to set the value of the %message% placeholder before displaying the progress bar:

1
2
3
4
5
6
7
8

// ...
$progressBar->setMessage('Start');
$progressBar->start();
// 0/100 -- Start

$progressBar->advance();
$progressBar->setMessage('Task is in progress...');
// 1/100 -- Task is in progress...

Messages can be combined with custom placeholders too. In this example, the progress bar uses the %message% and %filename% placeholders:

1
2
3
4

ProgressBar::setFormatDefinition('custom', ' %current%/%max% -- %message% (%filename%)');

$progressBar = new ProgressBar($output, 100);
$progressBar->setFormat('custom');

The setMessage() method accepts a second optional argument to set the value of the custom placeholders:

1
2
3
4
5
6
7
8

// ...
// $files = array('client-001/invoices.xml', '...');
foreach ($files as $filename) {
    $progressBar->setMessage('Importing invoices...');
    $progressBar->setMessage($filename, 'filename');
    $progressBar->advance();
    // 2/100 -- Importing invoices... (client-001/invoices.xml)
}