[Console][ProgressBar] Invalid example of usage of setMessage() method and %message% placeholder

[fre5h]

In the documentation of the ProgressBar helper there is a list of built-in placeholders. As the documentations says, built-in placeholders are:

• 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.

All of these placeholders are supported except the message. To be sure check this method https://github.com/symfony/console/blob/3.0/Helper/ProgressBar.php#L512
Also If we check the built-in formats https://github.com/symfony/console/blob/3.0/Helper/ProgressBar.php#L569 there is no format which uses the %message% placeholder out of box.

So the problem is that the next code from the documentation does not do out of box what we expect. It does not print the message, because any of the default formats does not include the %message% placeholder.

$bar->setMessage('Task starts');
$bar->start();

$bar->setMessage('Task in progress...');
$bar->advance();

// ...

$bar->setMessage('Task is finished');
$bar->finish();

No message won't be displayed in the progress bar. Even if you select any of built-in formats and set it $progressBar->setFormat('built-in-format'); it will not print the message. Because no of the built-in formats: normal, normal_nomax, verbose, verbose_nomax, very_verbose, very_verbose_nomax, debug, debug_nomax does not use the %message% placeholder.

So the current version of documentation confuses a bit. For example when I found this nice feature with messages for progress bar, I wanted to use it in my project. But it didn't work, the method setMessage() does nothing and I spent a lot of time to investigate this issue. So now I know two ways how to display the message in the progress bar.

The first is to set a custom format definition and add the %message% placeholder there (This is not clear from the documentation):

$progressBar = new ProgressBar($output, 10000);
$progressBar->setFormatDefinition('custom', ' %current%/%max% [%bar%] %message% %percent:3s%% %elapsed:6s%/%estimated:-6s%');
$progressBar->setFormat('custom');
$progressBar->setMessage('Start');
// start the loop...

This way is preferred, because it requires only to update the some part of docs.

And the second way is to edit the build-in formats https://github.com/symfony/console/blob/3.0/Helper/ProgressBar.php#L569 to include the %message% placeholder to some existing formats or maybe add new versions of formats which include this placeholder. But this case needs to make changes in the source code.

This mistake in the documentation affects all version since the 2.5 when the ProgressBar was introduced.

So if you agree with me that this missed peace of documentation is the issue, then let me know, I can fix it and send the pull request.

[xabbuh]

@fre5h A PR would be warmly welcomed. And if you could also open an issue for the code that would be great too.

[fre5h]

OK, I think it is better at first to send a fix to the code. If this fix be accepted, then there is no need to fix the documentation, because it will be correct.
Otherwise, if fix to the code be rejected, then I will create a fix to the docs.

[fabpot]

This is indeed a doc issue, see symfony/symfony#19035.

[HeahDude]

Can be closed?

[fre5h]

No, this is the issue. Documentation needs some small update to show that to use %message% placeholder user has to add custom format. Because there is no built-in format with supports %message% placeholder.

[HeahDude]

Alright! Thanks for the update.