Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Components
  4. Console
  5. Helpers
  6. Progress Bar
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Customizing the Progress Bar
    • Built-in Formats
    • Custom Formats
    • Bar Settings
    • Custom Placeholders
    • Custom Messages

Progress Bar

Edit this page

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

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

Progress Bar

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

To display progress details, use the ProgressBar, pass it a total number of units, and advance the progress as the command executes:

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

// creates a new progress bar (50 units)
$progressBar = new ProgressBar($output, 50);

// starts and displays the progress bar
$progressBar->start();

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

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

    // you can also advance the progress bar by more than 1 unit
    // $progressBar->advance(3);
}

// ensures that the progress bar is at 100%
$progressBar->finish();

Instead of advancing the bar by a number of steps (with the advance() method), you can also set the current progress by calling the setProgress() method.

2.6

The setProgress() method was called setCurrent() prior to Symfony 2.6.

Caution

Prior to version 2.6, the progress bar only works if your platform supports ANSI codes; on other platforms, no output is generated.

Tip

If your platform doesn't support ANSI codes, updates to the progress bar are added as new lines. To prevent the output from being flooded, adjust the setRedrawFrequency() accordingly. By default, when using a max, the redraw frequency is set to 10% of your max.

2.6

The setRedrawFrequency() method was introduced in Symfony 2.6.

If you don't know the number of steps in advance, just omit the steps argument when creating the ProgressBar instance:

1
$progressBar = new ProgressBar($output);

The progress will then be displayed as a throbber:

1
2
3
4
5
6
7
8
9
# no max steps (displays it like a throbber)
    0 [>---------------------------]
    5 [----->----------------------]
    5 [============================]

# max steps defined
 0/3 [>---------------------------]   0%
 1/3 [=========>------------------]  33%
 3/3 [============================] 100%

Whenever your task is finished, don't forget to call finish() to ensure that the progress bar display is refreshed with a 100% completion.

Note

If you want to output something while the progress bar is running, call clear() first. After you're done, call display() to show the progress bar again.

Customizing the 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:

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

Note

If you call a command with the quiet flag (-q), the progress bar won't be displayed.

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%

Tip

It is almost always better to redefine built-in formats instead of creating new ones as that allows the display to automatically vary based on the verbosity flag of the command.

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.

Tip

A format can contain any valid ANSI codes and can also use the Symfony-specific way to set colors:

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

Note

A format can span more than one line; that's very useful when you want to display more contextual information alongside the progress bar (see the example at the beginning of this article).

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

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 setRedrawFrequency(), so it updates on only some iterations:

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

2.6

The getProgress() method was called getStep() prior to Symfony 2.6.

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)
}
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Become certified from home

    Become certified from home

    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Sam Malone, a Symfony contributor

    Thanks Sam Malone for being a Symfony contributor

    1 commit • 360 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia