README

Flexible ascii progress bar.

Installation

composer require macroman/terminal-progress-bar

Usage

First we create a Bar, giving it a format string as well as the total, telling the progress bar when it will be considered complete. Then call tick() when needed.

// examples/basic.php
use TerminalProgress\Bar;

$pg = new Bar(1000);

for ($i = 0; $i < 1000; $i++) {
	usleep(10000);
	$pg->tick();
}

You can also use update(amount) to set the current tick value instead of ticking each time there is an increment:

// examples/update.php
use TerminalProgress\Bar;

$pg = new Bar(1000);

for ($i = 0; $i < 1000; $i++) {
	usleep(10000);
	$pg->update($i);
}

Options

These are properties in the object you can read/set:

symbolComplete Completion character defaulting to "="
symbolIncomplete Incomplete character defaulting to " "
throttle Minimum time between updates in seconds defaulting to 0.016
current Current tick
total Same value passed in when initialising
secondPrecision Number of decimal digits to use in "seconds" units
percentPrecision Number of decimal digits to use in "percentage" units
percent (read only) Current percentage completion
eta (read only) Estimate seconds until completion
rate (read only) Number of ticks per second
elapsed (read only) Seconds since initialisation

Tokens

These are tokens you can use in the format of your progress bar.

:bar the progress bar itself
:current current tick number
:total total ticks
:elapsed time elapsed in seconds
:percent completion percentage
:eta estimated completion time in seconds
:rate rate of ticks per second

Format example

// examples/format.php
// Full options
new Bar(10, "Progress: [:bar] - :current/:total - :percent% - Elapsed::elapseds - ETA::etas - Rate::rate/s");

// examples/format_percent.php
// Just percentage plus the bar
new Bar(10, ":bar :percent%");

// examples/format_no_bar.php
// You don't even have to have a bar
new Bar(10, "Look mum, no bar! :current/:total - :percent% - Elapsed::elapseds - ETA::etas - Rate::rate/s");

Interrupt example

To display a message during progress bar execution, use interrupt()

// examples/interrupt.php
$pg = new Bar(1000);

for ($i = 0; $i < 1000; $i++) {
	usleep(10000);
	if ($i % 100 == 0) {
		// Interupt every 100th tick
		$pg->interupt($i);
	}
	$pg->tick();
}

Symbols/Precision example

To change the symbols or precision used on the progress bar

// examples/symbols.php
$pg = new Bar(1000);

$pg->symbolComplete = "#";
$pg->symbolIncomplete = "-";

$pg->secondPrecision = 2;
$pg->percentPrecision = 4;

Throttle example

The draw interval is throttled at once per 100ms for performance. You can change this value if desired, eg lower for a smoother animation or higher if your work is resource intensive.

// examples/throttle.php
$pg = new Bar(1000);
$pg->throttle = 0.05; // Set a 50 millisecond throttle

License

See LICENSE

macroman / terminal-progress-bar

Maintainers

Details