Progress Indicator

Warning: You are browsing the documentation for Symfony 6.2, which is no longer maintained.

Read the updated version of this page for Symfony 7.2 (the current stable version).

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
# OutputInterface::VERBOSITY_NORMAL (CLI with no verbosity flag)
 \ Processing...
 | Processing...
 / Processing...
 - Processing...

# OutputInterface::VERBOSITY_VERBOSE (-v)
 \ Processing... (1 sec)
 | Processing... (1 sec)
 / Processing... (1 sec)
 - Processing... (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)

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
⠏ Processing...
⠛ Processing...
⠹ Processing...
⢸ Processing...

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