Progress Indicator

Progress indicators are useful to let users know that a command isn't stalled. Unlike progress bars, these indicators are used when the command duration is indeterminate (e.g. long-running commands, unquantifiable tasks, etc.)

They work by instantiating the ProgressIndicator class and advancing the progress as the command executes:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        use Symfony\Component\Console\Helper\ProgressIndicator;

// creates a new progress indicator
$progressIndicator = new ProgressIndicator($output);

// starts and displays the progress indicator with a custom message
$progressIndicator->start('Processing...');

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

    // advances the progress indicator
    $progressIndicator->advance();
}

// ensures that the progress indicator shows a final message
$progressIndicator->finish('Finished');
    

Customizing the Progress Indicator

Built-in Formats

By default, the information rendered on a progress indicator 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
20
        # OutputInterface::VERBOSITY_NORMAL (CLI with no verbosity flag)
 \ Processing...
 | Processing...
 / Processing...
 - Processing...
 ✔ Finished

# OutputInterface::VERBOSITY_VERBOSE (-v)
 \ Processing... (1 sec)
 | Processing... (1 sec)
 / Processing... (1 sec)
 - Processing... (1 sec)
 ✔ Finished (1 sec)

# OutputInterface::VERBOSITY_VERY_VERBOSE (-vv) and OutputInterface::VERBOSITY_DEBUG (-vvv)
 \ Processing... (1 sec, 6.0 MiB)
 | Processing... (1 sec, 6.0 MiB)
 / Processing... (1 sec, 6.0 MiB)
 - Processing... (1 sec, 6.0 MiB)
 ✔ Finished (1 sec, 6.0 MiB)
    

Tip

Call a command with the quiet flag (-q) to not display any progress indicator.

Instead of relying on the verbosity mode of the current command, you can also force a format via the second argument of the ProgressIndicator constructor:

        1
        $progressIndicator = new ProgressIndicator($output, 'verbose');
    

The built-in formats are the following:

normal
verbose
very_verbose

If your terminal doesn't support ANSI, use the no_ansi variants:

normal_no_ansi
verbose_no_ansi
very_verbose_no_ansi

Custom Indicator Values

Instead of using the built-in indicator values, you can also set your own:

        1
        $progressIndicator = new ProgressIndicator($output, 'verbose', 100, ['⠏', '⠛', '⠹', '⢸', '⣰', '⣤', '⣆', '⡇']);
    

The progress indicator will now look like this:

        1
2
3
4
5
        ⠏ Processing...
⠛ Processing...
⠹ Processing...
⢸ Processing...
✔ Finished
    

Once the progress finishes, it displays a special finished indicator (which defaults to ✔). You can replace it with your own:

        1
2
3
4
5
6
7
8
        $progressIndicator = new ProgressIndicator($output, finishedIndicatorValue: '🎉');

try {
    /* do something */
    $progressIndicator->finish('Finished');
} catch (\Exception) {
    $progressIndicator->finish('Failed', '🚨');
}
    

The progress indicator will now look like this:

        1
2
3
4
5
        \ Processing...
| Processing...
/ Processing...
- Processing...
🎉 Finished
    

7.2

The finishedIndicator parameter for the constructor was introduced in Symfony 7.2. The finishedIndicator parameter for method finish() was introduced in Symfony 7.2.

Customize Placeholders

A progress indicator uses placeholders (a name enclosed with the % character) to determine the output format. Here is a list of the built-in placeholders:

indicator: The current indicator;
elapsed: The time elapsed since the start of the progress indicator;
memory: The current memory usage;
message: used to display arbitrary messages in the progress indicator.

For example, this is how you can customize the message placeholder:

        1
2
3
4
5
6
7
        ProgressIndicator::setPlaceholderFormatterDefinition(
    'message',
    static function (ProgressIndicator $progressIndicator): string {
        // Return any arbitrary string
        return 'My custom message';
    }
);
    

Note

Placeholders customization is applied globally, which means that any progress indicator displayed after the setPlaceholderFormatterDefinition() call will be affected.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version