Updates PHP / Symfony / dependencies and add documentation

.github/workflows/build-docker-image-ci.yml

@@ -3,11 +3,23 @@ name: Build Docker image ci
 on:
     workflow_dispatch: ~
 
+permissions:
+    contents: read
+    packages: write
+
 jobs:
     build:
         name: Build Docker image ci
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
-            - run: echo "${{ secrets.DOCKER_HUB_TOKEN }}" | docker login --username steevanb --password-stdin
+            - uses: actions/checkout@v5
+
+            -
+                name: Log in to GitHub Container Registry
+                uses: docker/login-action@v3
+                with:
+                    registry: ghcr.io
+                    username: ${{ github.actor }}
+                    password: ${{ secrets.GITHUB_TOKEN }}
+
             - run: bin/ci/docker --push

.github/workflows/build-docker-image-release.yml

@@ -3,11 +3,23 @@ name: Build Docker image release
 on:
     workflow_dispatch: ~
 
+permissions:
+    contents: read
+    packages: write
+
 jobs:
     build:
-        name: Build Docker image release
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - run: echo "${{ secrets.DOCKER_HUB_TOKEN }}" | docker login --username steevanb --password-stdin
-            - run: bin/release/docker --push
+      name: Build Docker image ci
+      runs-on: ubuntu-latest
+      steps:
+          - uses: actions/checkout@v5
+
+          -
+              name: Log in to GitHub Container Registry
+              uses: docker/login-action@v3
+              with:
+                  registry: ghcr.io
+                  username: ${{ github.actor }}
+                  password: ${{ secrets.GITHUB_TOKEN }}
+
+          - run: bin/release/docker --push

.github/workflows/ci.yml

@@ -1,68 +1,19 @@
 name: CI
-on: [push]
-jobs:
-    phpcs:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - run: bin/ci/phpcs
-
-    phpstan:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                php: [--php=8.2, --php=8.3]
-                symfony: [--symfony=7.0, --symfony=7.1]
-        steps:
-            - uses: actions/checkout@v2
-            - uses: ./.github/actions/ci-env
-            - run: bin/ci/phpstan ${{ matrix.php }} ${{ matrix.symfony }}
-
-    phpdd:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - uses: ./.github/actions/ci-env
-            - run: bin/ci/phpdd
 
-    composer-normalize:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - run: bin/ci/composer-normalize
+on: [push]
 
-    composer-require-checker:
+jobs:
+    validate:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
-            - uses: ./.github/actions/ci-env
-            - run: bin/ci/composer-require-checker
+            - uses: actions/checkout@v5
 
-    composer-validate:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - run: bin/ci/composer-validate
+            - name: Cache vendor
+              uses: actions/cache@v4
+              with:
+                  path: vendor
+                  key: composer-${{ hashFiles('composer.json') }}
 
-    shellcheck:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - run: bin/ci/shellcheck
+            - run: bin/ci/env
 
-    unused-scanner:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
-            - run: bin/ci/unused-scanner
-
-    phpunit:
-        runs-on: ubuntu-latest
-        strategy:
-            matrix:
-                php: [--php=8.2, --php=8.3]
-                symfony: [--symfony=7.0, --symfony=7.1]
-        steps:
-            - uses: actions/checkout@v2
-            - uses: ./.github/actions/ci-env
-            - run: bin/ci/phpunit ${{ matrix.php }} ${{ matrix.symfony }}
+            - run: bin/ci/validate -v --theme=summary

README.md

@@ -7,15 +7,148 @@
 
 # php-parallel-processes
 
-Work in progress ;)
+Execute processes in parallel.
+
+Examples of use: start your environment, CI tools...
 
 # Installation
 
+## Use official Docker image
+
+You can use the official Docker image to not install anything:
+[steevanb/php-parallel-processes:x.y.z](https://hub.docker.com/r/steevanb/php-parallel-processes/tags).
+
+Example:
+```bash
+docker \
+    run \
+        --rm \
+        --tty \
+        --interactive \
+        --volume "$(pwd)":"$(pwd)" \
+        --workdir "$(pwd)" \
+        steevanb/php-parallel-processes:x.y.z \
+        php parallel-processes.php
+```
+
+### If your processes use docker
+
+If processes in `parallel-processes.php` use Docker, you have to add a volume on your Docker socket:
+```bash
+--volume /var/run/docker.sock:/var/run/docker.sock
 ```
+
+All official `php-parallel-processes` images have Docker and Docker compose installed, so you only need to add a volume on the socket.
+
+### alpine, bookworm and buster
+
+3 Docker images are provided for each `php-parallel-processes` version, use the one you want depending on your needs:
+ * `alpine`: smaller version, but could be "too much simple" sometimes
+ * `buster`: middle version, contains almost everything needed
+ * `bookworm`: larger version, should contain what you need
+
+## Install as Composer dependency
+
+If you want to add `php-parallel-processes` directly in your project:
+
+```bash
 composer require steevanb/php-parallel-processes ^1.0
 ```
 
-# Usage with Docker
+# Create processes configuration
 
-If you don't want to install it as dependency, you can use the official Docker image: 
-[steevanb/php-parallel-processes:x.y.z](https://hub.docker.com/r/steevanb/php-parallel-processes/tags).
+You need to create a configuration for your processes, written in PHP.
+
+Example: [bin/start.php](bin/start.php)
+
+## Basic example
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Steevanb\ParallelProcess\{
+    Console\Application\ParallelProcessesApplication,
+    Process\Process
+};
+use Symfony\Component\Console\Input\ArgvInput;
+
+# If you use the official Docker image, you should use the Composer global autoload
+require $_ENV['COMPOSER_GLOBAL_AUTOLOAD_FILE_NAME'];
+# If you use the Composer dependency version, you should use your Composer autoload
+require __DIR__ . '/vendor/autoload.php';
+
+(new ParallelProcessesApplication())
+    ->addProcess((new Process(['first', 'process']))->setName('First process'))
+    ->addProcess((new Process(['second', 'process']))->setName('Second process'))
+    ->run(new ArgvInput($argv));
+```
+
+## Configurations
+
+### Global timeout
+
+
+You can configure the global timeout with `ParallelProcessesApplication::setTimeout()`.
+
+Default value: `null` (no timeout).
+
+```php
+(new ParallelProcessesApplication())
+    // Timeout is in seconds, here we will have a 10s timeout
+    ->setTimeout(10)
+```
+
+### Refresh interval
+
+You can configure the refresh interval, to scan all processes status and start the next ones,
+with `ParallelProcessesApplication::setRefreshInterval()`.
+
+Default value: `10000` (10ms)
+
+```php
+(new ParallelProcessesApplication())
+    // Timeout is in microseconds, here we will have a 500ms timeout
+    ->setRefreshInterval(50000)
+```
+
+### Maximum processes in parallel
+
+You can configure the maximum number of processes in parallel
+with `ParallelProcessesApplication::setMaximumParallelProcesses()`.
+
+Default value: `null` (no maximum)
+
+```php
+(new ParallelProcessesApplication())
+    // Here we will have maximum 3 processes in parallel
+    ->setMaximumParallelProcesses(3)
+```
+
+### Theme
+
+`php-parallel-processes` comes with 2 themes:
+ * [default](src/Console/Application/Theme/DefaultTheme.php)
+   * Output everything
+   * Use verbosity (`-v`, `-vv` or `-vvv`) to add execution time and process outputs
+   * Should be used when you need to see live processes status, most of the time ;)
+ * [summary](src/Console/Application/Theme/SummaryTheme.php)
+   * Output only the start and the end of parallel processes
+   * Use verbosity (`-v`, `-vv` or `-vvv`) to add execution time and process outputs
+   * Should be used when you don't need to see live processes status, in CI for example
+
+Configure it with `ParallelProcessesApplication::setTheme()`:
+```php
+use Steevanb\ParallelProcess\Console\Application\Theme\DefaultTheme();
+
+(new ParallelProcessesApplication())
+    ->setTheme(new DefaultTheme())
+```
+
+You can also configure it in CLI with `--theme` (CLI override PHP configuration):
+```bash
+php parallel-processes.php --theme summary
+```
+
+You can create your own theme by implementing [ThemeInterface](src/Console/Application/Theme/ThemeInterface.php).

bin/DependenciesVersions.php

@@ -34,6 +34,7 @@ public function __construct(array $argv)
                 ->phpVersions
                 ->add('8.2')
                 ->add('8.3')
+                ->add('8.4')
                 ->setReadOnly();
         }
 
@@ -42,6 +43,8 @@ public function __construct(array $argv)
                 ->symfonyVersions
                 ->add('7.0')
                 ->add('7.1')
+                ->add('7.2')
+                ->add('7.3')
                 ->setReadOnly();
         }
     }

bin/ci/composer-require-checker

@@ -6,4 +6,4 @@ readonly ROOT_DIR="$(realpath "$(dirname "$(realpath "$0")")/../..")"
 
 source "${ROOT_DIR}"/bin/ci/dockerise.inc.bash
 
-composer-require-checker --ansi "${@}"
+composer-require-checker --ansi $@

bin/ci/phpcs

@@ -19,4 +19,4 @@ phpcs \
     --report=steevanb\\PhpCodeSniffs\\Reports\\Steevanb \
     --cache="${ROOT_DIR}"/var/ci/phpcs/cache \
     . \
-    "${@}"
+    $@

bin/ci/phpdd

@@ -6,4 +6,4 @@ readonly ROOT_DIR="$(realpath "$(dirname "$(realpath "$0")")/../..")"
 
 source "${ROOT_DIR}"/bin/ci/dockerise.inc.bash
 
-phpdd --exclude=vendor,var "${@}" .
+phpdd --exclude=vendor,var $@ .

bin/ci/phpstan

@@ -10,7 +10,7 @@ phpVersion=
 symfonyVersion=
 phpstanParameters=
 clearCache=false
-for arg in "${@}"; do
+for arg in "$@"; do
     if [ "${arg:0:6}" == "--php=" ]; then
         phpVersion="${arg:6}"
     elif [ "${arg:0:10}" == "--symfony=" ]; then

bin/ci/phpstan.php

@@ -36,4 +36,5 @@ function createPhpstanProcess(string $phpVersion, string $symfonyVersion): Proce
 
 (new ParallelProcessesApplication())
     ->addProcesses(createPhpstanProcesses($dependenciesVersions))
+    ->setRefreshInterval(50000)
     ->run(new ArgvInput($dependenciesVersions->getFilteredArgv()->toArray()));

bin/ci/phpunit

@@ -9,7 +9,7 @@ source "${ROOT_DIR}"/bin/ci/dockerise.inc.bash
 phpVersion=
 symfonyVersion=
 phpunitParameters=
-for arg in "${@}"; do
+for arg in "$@"; do
     if [ "${arg:0:6}" == "--php=" ]; then
         phpVersion="${arg:6}"
     elif [ "${arg:0:10}" == "--symfony=" ]; then
@@ -20,7 +20,7 @@ for arg in "${@}"; do
 done
 
 if [ "${phpVersion}" == "" ] || [ "${symfonyVersion}" == "" ]; then
-    php "${ROOT_DIR}"/bin/ci/phpunit.php "${@}"
+    php "${ROOT_DIR}"/bin/ci/phpunit.php $@
 else
     echo "PHP ${phpVersion} - Symfony ${symfonyVersion}"
 

bin/ci/phpunit-coverage

@@ -14,6 +14,6 @@ XDEBUG_MODE=coverage \
             --configuration "${ROOT_DIR}"/config/ci/phpunit.xml \
             --cache-result-file var/ci/phpunit/coverage/.phpunit.result.cache \
             --coverage-html "${ROOT_DIR}"/var/ci/phpunit/coverage/html \
-            "${@}"
+            $@
 
 printf "Open \e[33mvar/ci/phpunit/coverage/html/index.html\e[0m in your browser to see code coverage results.\n"

bin/ci/shellcheck

@@ -24,7 +24,8 @@ for fileToCheck in "${filesToCheck[@]}"; do
     # SC2155: Declare and assign separately to avoid masking return values.
     # SC2181: Check exit code directly with e.g. 'if mycmd;', not indirectly with $?.
     # SC2230: which is non-standard. Use builtin 'command -v' instead.
-    shellcheck --color=always --exclude SC1090,SC1091,SC2034,SC2086,SC2155,SC2181,SC2230 "${fileToCheck}"
+    # SC2068 (error): Double quote array expansions to avoid re-splitting elements.
+    shellcheck --color=always --exclude SC1090,SC1091,SC2034,SC2086,SC2155,SC2181,SC2230,SC2068 "${fileToCheck}"
     if [ ${?} != 0 ]; then
         exitCode=1
     fi

bin/ci/validate

@@ -6,4 +6,4 @@ readonly ROOT_DIR="$(realpath "$(dirname "$(realpath "$0")")/../..")"
 
 source "${ROOT_DIR}"/bin/ci/dockerise.inc.bash
 
-php "${ROOT_DIR}"/bin/ci/validate.php "${@}"
+php "${ROOT_DIR}"/bin/ci/validate.php $@

bin/ci/validate.php

@@ -20,4 +20,5 @@
     ->addProcess(new Process([__DIR__ . '/phpunit-coverage']))
     ->addProcess(new Process([__DIR__ . '/shellcheck']))
     ->addProcess(new Process([__DIR__ . '/unused-scanner']))
+    ->setRefreshInterval(50000)
     ->run(new ArgvInput($argv));

bin/composer

@@ -20,4 +20,4 @@ docker \
         --workdir "${ROOT_DIR}" \
         "${CI_DOCKER_IMAGE_NAME}" \
         composer \
-            "${@}"
+            $@