Introduction

Zend_ProgressBar is a component to create and update progressbars in different environments. It consists of a single backend, which outputs the progress through one of the multiple adapters. On every update, it takes an absolute value and optionally a status message, and then calls the adapter with some precalculated values like percentage and estimated time left.

Basic Usage of Zend_Progressbar

Zend_ProgressBar is quite easy in its usage. You simply create a new instance of Zend_Progressbar, defining a min- and a max-value, and choose an adapter to output the data. If you want to process a file, you would do something like:

$progressBar = new Zend_ProgressBar($adapter, 0, $fileSize);
 
while (!feof($fp)) {
    // Do something
 
    $progressBar->update($currentByteCount);
}
 
$progressBar->finish();

In the first step, an instance of Zend_ProgressBar is created, with a specific adapter, a min-value of 0 and a max-value of the total filesize. Then a file is processed and in every loop the progressbar is updated with the current byte count. At the end of the loop, the progressbar status is set to finished.

You can also call the update() method of Zend_ProgressBar without arguments, which just recalculates ETA and notifies the adapter. This is useful when there is no data update but you want the progressbar to be updated.

Persistent progress

If you want the progressbar to be persistent over multiple requests, you can give the name of a session namespace as fourth argument to the constructor. In that case, the progressbar will not notify the adapter within the constructor, but only when you call update() or finish(). Also the current value, the status text and the start time for ETA calculation will be fetched in the next request run again.

Standard adapters

Zend_ProgressBar comes with the following three adapters:

Zend_ProgressBar_Adapter_Console

Zend_ProgressBar_Adapter_Console is a text-based adapter for terminals. It can automatically detect terminal widths but supports custom widths as well. You can define which elements are displayed with the progressbar and as well customize the order of them. You can also define the style of the progressbar itself.

Note: Automatic console width recognition
shell_exec is required for this feature to work on *nix based systems. On windows, there is always a fixed terminal width of 80 character, so no recognition is required there.

You can set the adapter options either via the set* methods or give an array or a Zend_Config instance with options as first parameter to the constructor. The available options are:

outputStream: A different output-stream, if you don't want to stream to STDOUT. Can be any other stream like php://stderr or a path to a file.
width: Either an integer or the AUTO constant of Zend_Console_ProgressBar.
elements: Either NULL for default or an array with at least one of the following constants of Zend_Console_ProgressBar as value:
- ELEMENT_PERCENT: The current value in percent.
- ELEMENT_BAR: The visual bar which display the percentage.
- ELEMENT_ETA: The automatic calculated ETA. This element is firstly displayed after five seconds, because in this time, it is not able to calculate accurate results.
- ELEMENT_TEXT: An optional status message about the current process.
textWidth: Width in characters of the ELEMENT_TEXT element. Default is 20.
charset: Charset of the ELEMENT_TEXT element. Default is utf-8.
barLeftChar: A string which is used left-hand of the indicator in the progressbar.
barRightChar: A string which is used right-hand of the indicator in the progressbar.
barIndicatorChar: A string which is used for the indicator in the progressbar. This one can be empty.

Zend_ProgressBar_Adapter_JsPush

Zend_ProgressBar_Adapter_JsPush is an adapter which let's you update a progressbar in a browser via Javascript Push. This means that no second connection is required to gather the status about a running process, but that the process itself sends its status directly to the browser.

You can set the adapter options either via the set* methods or give an array or a Zend_Config instance with options as first parameter to the constructor. The available options are:

updateMethodName: The javascript method which should be called on every update. Default value is Zend_ProgressBar_Update.
finishMethodName: The javascript method which should be called after finish status was set. Default value is NULL, which means nothing is done.

The usage of this adapter is quite simple. First you create a progressbar in your browser, either with JavaScript or previously created with plain HTML. Then you define the update method and optionally the finish method in JavaScript, both taking a json object as single argument. Then you call a webpage with the long-running process in a hidden iframe or object tag. While the process is running, the adapter will call the update method on every update with a json object, containing the following parameters:

current: The current absolute value
max: The max absolute value
percent: The calculated percentage
timeTaken: The time how long the process ran yet
timeRemaining: The expected time for the process to finish
text: The optional status message, if given

Example #1 Basic example for the client-side stuff

This example illustrates a basic setup of HTML, CSS and JavaScript for the JsPush adapter

<div id="zend-progressbar-container">
    <div id="zend-progressbar-done"></div>
</div>
 
<iframe src="long-running-process.php" id="long-running-process"></iframe>

#long-running-process {
    position: absolute;
    left: -100px;
    top: -100px;
 
    width: 1px;
    height: 1px;
}
 
#zend-progressbar-container {
    width: 100px;
    height: 30px;
 
    border: 1px solid #000000;
    background-color: #ffffff;
}
 
#zend-progressbar-done {
    width: 0;
    height: 30px;
 
    background-color: #000000;
}

function Zend_ProgressBar_Update(data)
{
    document.getElementById('zend-progressbar-done').style.width =
         data.percent + '%';
}

This will create a simple container with a black border and a block which indicates the current process. You should not hide the iframe or object by display: none;, as some browsers like Safari 2 will not load the actual content then.

Instead of creating your custom progressbar, you may want to use one of the available JavaScript libraries like Dojo, jQuery etc. For example, there are:

Dojo: http://dojotoolkit.org/reference-guide/dijit/ProgressBar.html
jQuery: http://t.wits.sg/2008/06/20/jquery-progress-bar-11/
MooTools: http://davidwalsh.name/dw-content/progress-bar.php
Prototype: http://livepipe.net/control/progressbar

Note: Interval of updates
You should take care of not sending too many updates, as every update has a min-size of 1kb. This is a requirement for the Safari browser to actually render and execute the function call. Internet Explorer has a similar limitation of 256 bytes.

Zend_ProgressBar_Adapter_JsPull

Zend_ProgressBar_Adapter_JsPull is the opposite of jsPush, as it requires to pull for new updates, instead of pushing updates out to the browsers. Generally you should use the adapter with the persistence option of the Zend_ProgressBar. On notify, the adapter sends a JSON string to the browser, which looks exactly like the JSON string which is send by the jsPush adapter. The only difference is, that it contains an additional parameter, finished, which is either FALSE when update() is called or TRUE, when finish() is called.

You can set the adapter options either via the set*() methods or give an array or a Zend_Config instance with options as first parameter to the constructor. The available options are:

exitAfterSend: Exits the current request after the data were send to the browser. Default is TRUE.