|
| 1 | +# PHP CLI Progress Bar |
| 2 | + |
| 3 | +[](https://packagist.org/packages/nickbeen/php-cli-progress-bar) |
| 4 | +[](https://packagist.org/packages/nickbeen/php-cli-progress-bar) |
| 5 | +[](https://packagist.org/packages/nickbeen/php-cli-progress-bar) |
| 6 | +[](https://packagist.org/packages/nickbeen/php-cli-progress-bar) |
| 7 | +[](https://packagist.org/packages/nickbeen/php-cli-progress-bar) |
| 8 | + |
| 9 | +For creating minimal progress bars in PHP CLI scripts. |
| 10 | +It has no dependencies, but requires PHP 8.0 or higher. |
| 11 | +This library is mainly built for iterating to countable variables, but also works easily with ticking through less structured step-by-step scripts. |
| 12 | + |
| 13 | +Many PHP CLI progress bars have been written in the past, but most haven't been updated in years. |
| 14 | +This library uses the latest PHP features such as return types, named arguments and constructor property promotions. |
| 15 | +For creating richer, more customizable progress bars, check alternatives such as the progress bar helper included in the [symfony/console](https://symfony.com/doc/current/components/console/helpers/progressbar.html) package. |
| 16 | + |
| 17 | +## Requirements |
| 18 | +- PHP 8.0 or higher |
| 19 | + |
| 20 | +## Installation |
| 21 | + |
| 22 | +Install the library into your project with Composer. |
| 23 | + |
| 24 | +``` |
| 25 | +composer require nickbeen/php-cli-progress-bar |
| 26 | +``` |
| 27 | + |
| 28 | +## Usage |
| 29 | + |
| 30 | +With this library you can display a progress bar in a PHP CLI script to indicate the script is doing its work and how far it has progressed. |
| 31 | +All you need to do is start displaying the progress bar, tick through the steps the script goes through and finish the display of the progress bar. |
| 32 | + |
| 33 | +``` |
| 34 | + 1/100 [#...........................] 1% (00:00:16) |
| 35 | +``` |
| 36 | + |
| 37 | +``` |
| 38 | + 64/100 [##################..........] 64% (00:00:07) |
| 39 | +``` |
| 40 | + |
| 41 | +``` |
| 42 | +100/100 [############################] 100% |
| 43 | +``` |
| 44 | + |
| 45 | +### Manually progressing |
| 46 | + |
| 47 | +It is possible to tick through the steps of your scripts manually when the steps in your script cannot be looped. |
| 48 | +Each tick adds one progression, but you can override the progression made by including an integer in `tick()`. |
| 49 | + |
| 50 | +You do need to set `maxProgress` for the progress bar to display the correct numbers by including it in the constructor. |
| 51 | +If you don't know the maxProgress during initialization, you can set it later with the `setMaxProgress()` method. |
| 52 | + |
| 53 | +```php |
| 54 | +$progressBar = new \NickBeen\ProgressBar\ProgressBar(maxProgress: 62); |
| 55 | +$progressBar->start(); |
| 56 | + |
| 57 | +doSomething(); |
| 58 | +$progressBar->tick(); |
| 59 | + |
| 60 | +doSomethingElse(); |
| 61 | +$progressBar->tick(); |
| 62 | + |
| 63 | +doSixtyTasks(); |
| 64 | +$progressBar->tick(60); |
| 65 | + |
| 66 | +$progressBar->finish(); |
| 67 | +``` |
| 68 | + |
| 69 | +If you have a little more structure in your step-by-step code, you can easily place `tick()` in a for loop. |
| 70 | +There is however a more convenient method when dealing with e.g. arrays. |
| 71 | + |
| 72 | +### Iterating through arrays or traversable instances |
| 73 | + |
| 74 | +This class method works with anything of the pseudo-type [iterable](https://www.php.net/manual/en/language.types.iterable.php) which includes any array or any instance of [Traversable](https://www.php.net/manual/en/class.traversable.php). |
| 75 | +The `iterate()` method automatically handles starting the progress bar, managing ticking through the iteration and finally finish displaying the progress bar. |
| 76 | + |
| 77 | +```php |
| 78 | +$array = [ |
| 79 | + 1 => 'A', |
| 80 | + 2 => 'B', |
| 81 | + 3 => 'C', |
| 82 | +]; |
| 83 | + |
| 84 | +$progressBar = new \NickBeen\ProgressBar\ProgressBar(); |
| 85 | + |
| 86 | +foreach ($progressBar->iterate($array as $key => $value);) { |
| 87 | + echo "$key: $value" . PHP_EOL; |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +### Interact with the progress bar |
| 92 | + |
| 93 | +It is possible to interact with the progress bar during its run. |
| 94 | +You can retrieve the estimated time to finish, the progress it has made, the maximum progress that has been set and the amount of completion in percentage. |
| 95 | +You can use this information e.g. for notifications or other tasks in the background. |
| 96 | + |
| 97 | +```php |
| 98 | +foreach ($progressBar->iterate($array);) { |
| 99 | + // Some custom notification |
| 100 | + sendToDiscord($progressBar->getEstimatedTime()); |
| 101 | + |
| 102 | + // Some custom task application |
| 103 | + syncWithCloud($progressBar->getPercentage()) |
| 104 | + |
| 105 | + // Some other custom application |
| 106 | + sendToRaspberryPiDisplay($progressBar->getProgress(), $progressBar->getMaxProgress()) |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +## License |
| 111 | + |
| 112 | +This library is licensed under the MIT License (MIT). See the [LICENSE](LICENSE.md) for more details. |
0 commit comments