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