README

Version: v1.1.0
Date: May 23 2019
Release notes
GitHub repository

A simple, yet powerful, class for rendering progress bars to the command-line.

Installation

This library is installed via Composer. To install, use composer require pointybeard/helpers-cli-progressbar or add "pointybeard/helpers-cli-progressbar": "~1.0" to your composer.json file.

And run composer to update your dependencies:

$ curl -s http://getcomposer.org/installer | php
$ php composer.phar update

Requirements

This library makes use of the PHP Helpers: Sliding Average (pointybeard/helpers-statistics-slidingaverage), PHP Helpers: Command-line Colours (pointybeard/helpers-cli-colour), and PHP Helpers: Time Functions (pointybeard/helpers-functions-time) packages. They are installed automatically via composer.

To include all the PHP Helpers packages on your project, use composer require pointybeard/helpers or add "pointybeard/helpers": "~1.0" to your composer file.

Usage

Include this library in your PHP files with use pointybeard\Helpers\Cli\ProgressBar and instanciate the ProgressBar\ProgressBar class like so:

<?php

declare(strict_types=1);

include __DIR__.'/vendor/autoload.php';

use pointybeard\Helpers\Cli\ProgressBar;
use pointybeard\Helpers\Cli\Colour;

$progress = (new ProgressBar\ProgressBar(rand(10000, 20000)))
    ->length(30)
    ->foreground(Colour\Colour::FG_GREEN)
    ->background(Colour\Colour::BG_DEFAULT)
    ->format('{{PROGRESS_BAR}} {{PERCENTAGE}}% {{COMPLETED}}/{{TOTAL}} ({{REMAINING_TIME}} remaining)')
;

// Optional. Seeds the start time of the progress bar. time() is used
// if omitted.
$progress->start();

do {
    // This moves the progress forward (default is 1 unit) and redraws it
    $progress->advance();

    // Slow the script down so we can see what's happening
    usleep(rand(5000, 20000));
} while ($progress->remaining() > 0);

echo PHP_EOL.'Work complete!'.PHP_EOL;

Placeholders

The format of the progress bar can be modified using the format method. The default format is {{PROGRESS_BAR}} {{PERCENTAGE}}% {{COMPLETED}}/{{TOTAL}} ({{ELAPSED_TIME}} elapsed, approx. {{REMAINING_TIME}} remaining).

Placeholders available are:

PROGRESS_BAR
PERCENTAGE
COMPLETED
TOTAL
ELAPSED_TIME
REMAINING_TIME

Support

If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.

Contributing

We encourage you to contribute to this project. Please check out the Contributing documentation for guidelines about how to get involved.

License

"PHP Helpers: Command-line Progress Bar" is released under the MIT License.

pointybeard / helpers-cli-progressbar

Maintainers

Details