Progress Bars

Standard Adapters

zend-progressbar comes with the following three adapters:

• Zend\Progressbar\Adapter\Console
• Zend\Progressbar\Adapter\JsPush
• Zend\ProgressBar\Adapter\JsPull

Console Adapter

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 as well customize the order of them. You can also define the style of the progressbar itself.

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 characters, so no recognition is required there.

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

To determine which elements to display in the progressbar, use one or more of the following constants:

JsPush Adapter

Zend\ProgressBar\Adapter\JsPush is an adapter allowing you to update a browser-based progressbar 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 provide an array or Traversable instance with options as the first parameter to the constructor. The available options are:

To use this adapter, first create a progressbar in your browser, either with JavaScript or plain HTML. Then define the update method and optionally a finish method in JavaScript; both should expect a JSON object as the only argument. Then 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:

Basic example for the client-side

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 container with a black border and a block which indicates the current process. You should not hide the iframe or object using display: none;, as some browsers (such as 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.:

• Dojo
• jQuery
• MooTools
• Prototype

Interval of updates

Do not send too many updates, as every update has a minimum 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.

JsPull Adapter

Zend\ProgressBar\Adapter\JsPull is the opposite of JsPush, as it requires the browser to pull for new updates, instead of pushing updates directly without intervention.

In general, you should use this adapter with the persistence option of the Zend\ProgressBar\ProgressBar. On notify, the adapter sends a JSON string to the browser, which looks exactly like the JSON string which is sent by the JsPush adapter, with one difference: 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 Traversable instance with options as first parameter to the constructor. The available options are: