Initial commit

.editorconfig

@@ -0,0 +1,12 @@
+; This file is for unifying the coding style for different editors and IDEs.
+; More information at http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_size = 4
+indent_style = space
+trim_trailing_whitespace = true

.gitattributes

@@ -0,0 +1,14 @@
+# Automatically normalize line endings
+*                  text=auto
+
+# Explicitly set diffs
+*.md               diff=markdown
+*.php              diff=php
+
+# Ignore all test and documentation
+/.editorconfig     export-ignore
+/.gitattributes    export-ignore
+/.github           export-ignore
+/.gitignore        export-ignore
+/phpunit.xml.dist  export-ignore
+/tests             export-ignore

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @nickbeen

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,48 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug"]
+assignees:
+    - nickbeen
+body:
+    - type: markdown
+      attributes:
+          value: |
+              Thanks for taking the time to fill out this bug report!
+    - type: input
+      id: library-version
+      attributes:
+          label: Library version
+          description: "What version of php-cli-progress-bar do you have installed?"
+          placeholder: "1.0.0"
+      validations:
+          required: true
+    - type: input
+      id: php-version
+      attributes:
+          label: PHP version
+          description: "What version of PHP do you have installed?"
+          placeholder: "8.0.0"
+      validations:
+          required: true
+    - type: textarea
+      id: bug-description
+      attributes:
+          label: Bug description
+          description: What went wrong? What did you expect to happen?
+      validations:
+          required: true
+    - type: textarea
+      id: sample-code
+      attributes:
+          label: Sample code
+          description: If applicable, provide relevant PHP code.
+          render: PHP
+    - type: checkboxes
+      id: terms
+      attributes:
+          label: Code of Conduct
+          description: By submitting this issue, you agree to follow the [Code of Conduct](https://github.com/nickbeen/.github/blob/main/.github/CODE_OF_CONDUCT.md)
+          options:
+              - label: I agree to follow the Code of Conduct
+                required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+    - name: Help, questions and ideas
+      url: https://github.com/nickbeen/php-cli-progressbar/discussions
+      about: "Please start a new discussion"

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+
+    - package-ecosystem: "github-actions"
+      directory: "/"
+      schedule:
+          interval: "weekly"
+          time: "11:11"
+          day: "sunday"

.github/workflows/run-tests.yml

@@ -0,0 +1,35 @@
+name: Run tests
+
+on:
+    pull_request:
+
+jobs:
+    run-tests:
+
+        strategy:
+            fail-fast: false
+            matrix:
+                php: [8.1, 8.0]
+                os: [ubuntu-latest, windows-latest]
+
+        name: PHP ${{ matrix.php }} - ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v3
+
+            - name: Setup PHP
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: ${{ matrix.php }}
+                  coverage: none
+
+            - name: Setup problem matcher
+              run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+
+            - name: Install dependencies
+              run: composer update --prefer-dist
+
+            - name: Run tests
+              run: vendor/bin/phpunit

.gitignore

@@ -0,0 +1,5 @@
+.idea
+.phpunit.result.cache
+composer.lock
+phpunit.xml
+vendor

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Nick Been
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,112 @@
+# PHP CLI Progress Bar
+
+[![Latest version](https://img.shields.io/packagist/v/nickbeen/php-cli-progress-bar)](https://packagist.org/packages/nickbeen/php-cli-progress-bar)
+[![Build status](https://img.shields.io/github/workflow/status/nickbeen/php-cli-progress-bar/Run%20tests)](https://packagist.org/packages/nickbeen/php-cli-progress-bar)
+[![Total downloads](https://img.shields.io/packagist/dt/nickbeen/php-cli-progress-bar)](https://packagist.org/packages/nickbeen/php-cli-progress-bar)
+[![PHP Version](https://img.shields.io/packagist/php-v/nickbeen/php-cli-progress-bar)](https://packagist.org/packages/nickbeen/php-cli-progress-bar)
+[![License](https://img.shields.io/packagist/l/nickbeen/php-cli-progress-bar)](https://packagist.org/packages/nickbeen/php-cli-progress-bar)
+
+For creating minimal progress bars in PHP CLI scripts.
+It has no dependencies, but requires PHP 8.0 or higher.
+This library is mainly built for iterating to countable variables, but also works easily with ticking through less structured step-by-step scripts.
+
+Many PHP CLI progress bars have been written in the past, but most haven't been updated in years.
+This library uses the latest PHP features such as return types, named arguments and constructor property promotions.
+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.
+
+## Requirements
+- PHP 8.0 or higher
+
+## Installation
+
+Install the library into your project with Composer.
+
+```
+composer require nickbeen/php-cli-progress-bar
+```
+
+## Usage
+
+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.
+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.
+
+```
+  1/100 [#...........................]   1% (00:00:16)
+```
+
+```
+ 64/100 [##################..........]  64% (00:00:07)
+```
+
+```
+100/100 [############################] 100%
+```
+
+### Manually progressing
+
+It is possible to tick through the steps of your scripts manually when the steps in your script cannot be looped.
+Each tick adds one progression, but you can override the progression made by including an integer in `tick()`.
+
+You do need to set `maxProgress` for the progress bar to display the correct numbers by including it in the constructor.
+If you don't know the maxProgress during initialization, you can set it later with the `setMaxProgress()` method.
+
+```php
+$progressBar = new \NickBeen\ProgressBar\ProgressBar(maxProgress: 62);
+$progressBar->start();
+
+doSomething();
+$progressBar->tick();
+
+doSomethingElse();
+$progressBar->tick();
+
+doSixtyTasks();
+$progressBar->tick(60);
+
+$progressBar->finish();
+```
+
+If you have a little more structure in your step-by-step code, you can easily place `tick()` in a for loop.
+There is however a more convenient method when dealing with e.g. arrays.
+
+### Iterating through arrays or traversable instances
+
+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).
+The `iterate()` method automatically handles starting the progress bar, managing ticking through the iteration and finally finish displaying the progress bar.
+
+```php
+$array = [
+    1 => 'A',
+    2 => 'B',
+    3 => 'C',
+];
+
+$progressBar = new \NickBeen\ProgressBar\ProgressBar();
+
+foreach ($progressBar->iterate($array as $key => $value);) {
+    echo "$key: $value" . PHP_EOL;
+}
+```
+
+### Interact with the progress bar
+
+It is possible to interact with the progress bar during its run.
+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.
+You can use this information e.g. for notifications or other tasks in the background.
+
+```php
+foreach ($progressBar->iterate($array);) {
+    // Some custom notification
+    sendToDiscord($progressBar->getEstimatedTime());
+
+    // Some custom task application
+    syncWithCloud($progressBar->getPercentage())
+
+    // Some other custom application
+    sendToRaspberryPiDisplay($progressBar->getProgress(), $progressBar->getMaxProgress())
+}
+```
+
+## License
+
+This library is licensed under the MIT License (MIT). See the [LICENSE](LICENSE.md) for more details.

composer.json

@@ -0,0 +1,42 @@
+{
+    "name": "nickbeen/php-cli-progress-bar",
+    "description": "For creating minimal progress bars in PHP CLI scripts",
+    "type": "library",
+    "keywords": [
+        "php",
+        "cli",
+        "progress bar"
+    ],
+    "homepage": "https://github.com/nickbeen/php-cli-progress-bar",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Nick Been",
+            "role": "Developer"
+        }
+    ],
+    "require": {
+        "php": "^8.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5"
+    },
+    "autoload": {
+        "psr-4": {
+            "NickBeen\\ProgressBar\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "NickBeen\\ProgressBar\\Tests\\": "tests"
+        }
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit"
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true
+}

phpunit.xml.dist

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+    beStrictAboutOutputDuringTests="true"
+    bootstrap="vendor/autoload.php"
+    colors="true"
+    executionOrder="random"
+    failOnEmptyTestSuite="true"
+    failOnRisky="true"
+    failOnWarning="true"
+    stderr="true"
+    verbose="true">
+    <php>
+        <ini name="display_errors" value="On"/>
+        <ini name="error_reporting" value="-1"/>
+    </php>
+    <testsuites>
+        <testsuite name="tests">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>