Zend Framework: Zend_ProgessBar Component Proposal

Proposed Component Name	Zend_ProgessBar
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_ProgessBar
Proposers	Ben Scholzen Zend Liaison Ralph Schindler
Revision	1.0 - 20 August 2008: Initial proposal. 2.0 - 06 September 2008: Refactoring from Zend_Console_ProgressBar to Zend_ProgressBar. (wiki revision: 9)

Zend_ProgessBar is designed to give developers a simple option to display progess to the user in multiple enviroments. In the first stage, it will support a console adapter, which supports three elements, which are a percentage value, a bar, and an automatic calculated ETA, of which all can be custom arranged and partially leaved out. Another available adapter will be Comet, which serves the purpose of updating progressbars in the web.

2. References

http://en.wikipedia.org/wiki/Progress_bar

3. Component Requirements, Constraints, and Acceptance Criteria

This component will not be able to watch other classes (this would require some hacky multi-processing, which would not work on windows).
This component will automatically calculate an ETA.
This component will allow to set an additional status text.
The console adapter will work on both nix (linux, bsd, solaris, mac, etc) and win systems.
The console adapter will automatically try to determine the terminal width in auto mode.
The console adapter will allow setting a custom width.
The console adapter will allow to customize the style of the progressbar.
The comet adapter will allow updating a progressbar via javascript, while an action is running.

4. Dependencies on Other Framework Components

Zend_Exception
Zend_Json

5. Theory of Operation

First an instance of Zend_ProgessBar is created, with setting min-, max value (those default to 0 and 100), as well as a frontend adapter. After that the user can call the ::update($value, $text) method to update the progessbar.

6. Milestones / Tasks

Milestone 1: [DONE] Working prototype checked into the incubator.
Milestone 2: [DONE] Unit tests exist, work, and are checked into SVN.
Milestone 3: [DONE] Documentation exists.
Milestone 4: Component is approved and moved into trunk.

7. Class Index

Zend_ProgessBar
Zend_ProgessBar_Adapter_Interface
Zend_ProgessBar_Adapter_Console
Zend_ProgessBar_Adapter_Comet

8. Use Cases

UC-01

<?php
require_once 'Zend/ProgressBar.php';
require_once 'Zend/ProgressBar/Adapter/Console.php';

fwrite(STDOUT, "Please wait, while I sleep:\n");

$adapter     = new Zend_ProgressBar_Adapter_Console()
$progressBar = new Zend_ProgressBar(0, 100, $adapter);

for ($i = 1; $i <= 100; $i++) {
    $progressBar->update($i);
    usleep(1000000);
}

fwrite(STDOUT, "\n");

9. Class Skeletons

class Zend_ProgressBar
{
    /**
     * Create a new progressbar backend.
     *
     * @param  float                              $min
     * @param  float                              $max
     * @param  Zend_ProgressBar_Adapter_Interface $adapter
     * @throws Zend_ProgressBar_Exception When $min is greater or equal to $max
     */
    public function __construct($min = 0, $max = 100, Zend_ProgressBar_Adapter_Interface $adapter);
    
    /**
     * Update the progressbar
     *
     * @param  float  $value
     * @param  string $text
     * @return void
     */
    public function update($value = null, $text = null);
    
    /**
     * Update the progressbar to the next value
     *
     * @param  string $text
     * @return void
     */
    public function next($diff = 1, $text = null);
}

interface Zend_ProgressBar_Adapter_Interface
{
    /**
     * Update the progressbar
     *
     * @param  float   $current       Current progress value
     * @param  float   $max           Max progress value
     * @param  flaot   $percent       Current percent value
     * @param  integer $timeTaken     Taken time in seconds
     * @param  integer $timeRemaining Remaining time in seconds
     * @param  string  $text          Status text
     * @return void
     */
    public function update($current, $max, $percent, $timeTaken, $timeRemaining, $text);
}

class Zend_ProgressBar_Adapter_Console implements Zend_ProgressBar_Adapter_Interface
{
    /**
     * Create a new console adapter.
     * 
     * If $width is set to AUTO, it will try to determine the current window
     * width and in case default to 80. $asynchronous defines, wether the
     * progressbar should be run in another process or not. $elements may be
     * either NULL for default or an array with the class constants ELEMENT_*.
     * All elements have a fixed width (except ELEMENT_BAR, which will extend
     * to the full width available) and will be seperated by a space.
     *
     * @param  integer $width
     * @param  array   $elements
     * @param  array   $elementOptions
     * @throws Zend_ProgressBar_Adapter_Exception When an invalid argument is in the $elements list
     */
    public function __construct($width = self::AUTO, array $elements = null, array $elementOptions = null);
       
    /**
     * Close local stdout, when open
     */
    public function __destruct();
    
    /**
     * Defined by Zend_ProgressBar_Adapter_Interface
     *
     * @param  float   $current       Current progress value
     * @param  float   $max           Max progress value
     * @param  flaot   $percent       Current percent value
     * @param  integer $timeTaken     Taken time in seconds
     * @param  integer $timeRemaining Remaining time in seconds
     * @param  string  $text          Status text
     * @return void
     */
    public function update($current, $max, $percent, $timeTaken, $timeRemaining, $text);

    /**
     * Outputs given data to STDOUT.
     * 
     * This split-off is required for unit-testing.
     *
     * @param  string $data
     * @return void
     */
    protected function _outputData($data);
}

Page Operations

Browse Space

Zend_ProgressBar - Ben Scholzen

Labels