Developer Newsletter

PEAR Manual
Prev	Chapter 34. Console	Next

Console_ProgressBar

Console_ProgressBar displays a customizable progress bar in the console/terminal.

Example 34-3. Some progress bar examples

This will display a very simple bar:
=====================================================

A more complicated bar, showing current status in numbers as well:
* 3/7 [==========================>-------------------------------------]  42.86%

Showing elapsed time, and using ANSI codes:
   - 109/345 [========>------------------]  31.59% Elapsed Time: 00:03.94

Showing an estimate for the remaining time:
- 105/345 [============>-------------------------------]  30.43% ETA: 00:11.52

Things to setup

require_once "Console/ProgressBar.php"
Create a new instance of Console_ProgressBar.
Call update() whenever some progress has been made.
(optional) erase(). after you're finished.

Example 34-4. Simple progressbar example

<?php
require_once 'Console/ProgressBar.php';
$bar = new Console_ProgressBar('[%bar%] %percent%', '=>', ' ', 80, 7);

//do some processing here
for ($i = 0; $i <= 7; $i++) {
    $bar->update($i);
    sleep(1);
}
echo "\n";
?>

[=======================================>                              ]  57.14%

Creating the bar

In the example we create the progress bar instance with five parameters: The format string, bar string, empty string, console width and the target number.

The first parameter, format string, defines the layout of the whole progress bar. It may contain any character and has some variables that get replaced:

%bar% is the actual progress bar.
%current% is the current value set via update().
%max% is replaced with the maximum value set by the constructor (target number).
%fraction% - the same as %current%/%max%.
%percent% - status in percent.
%elapsed% - elapsed time.
%estimate% - an estimation of how long the progress will take.

The second argument is the string that is going to fill the progress bar. In the above example, the string "=>" was used. If the string you pass is too short (like "=>" in this example), the leftmost character is used to pad it to the needed size. If the string you pass is too long, excessive characters are stripped from the left.

The third argument is the string that fills the "empty" space in the progress bar. In the above example, that would be "-". If the string you pass is too short (like "-" in this example), the rightmost character is used to pad it to the needed size. If the string you pass is too long, excessive characters are stripped from the right.

The fourth argument specifies the width of the display. A normal console/terminal is 80 chars, so pass 80 here. Currently there is no method to determine the current width of a terminal.

The fifth argument is the target number of the progress bar. For example, if you wanted to display a progress bar for a download of a file that is 115 KB big, you would pass 115 here.

Updating and finishing

After setting up the progress bar, you can start doing the real work - up- or downloading files, calculating something etc. Whenever you did a step forward, call update() with the current step number.

When you're finished, you may want to remove the progress bar from screen - use erase() for this.

Prev	Home	Next
Console_Getopt::readPHPArgv	Up	Console_Table