V2.0

.dockerignore

@@ -0,0 +1,8 @@
+.git
+.idea
+.vscode
+vendor
+build
+.phpunit.result.cache
+node_modules
+terminals

.gitattributes

@@ -1,2 +1,3 @@
 /tests export-ignore
 /snippets export-ignore
+*.sh text eol=lf

.github/workflows/tests.yml

@@ -0,0 +1,183 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - v2.0
+  pull_request:
+
+jobs:
+  matrix:
+    name: Laravel ${{ matrix.laravel }} / PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - laravel: '10'
+            php: '8.1'
+            testbench: '^8.0'
+          - laravel: '11'
+            php: '8.2'
+            testbench: '^9.0'
+          - laravel: '12'
+            php: '8.2'
+            testbench: '^10.0'
+          - laravel: '13'
+            php: '8.3'
+            testbench: '^11.0'
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_DATABASE: helpers_test
+          MYSQL_USER: helpers
+          MYSQL_PASSWORD: secret
+          MYSQL_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 -uhelpers -psecret"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+
+    env:
+      REDIS_HOST: 127.0.0.1
+      REDIS_PORT: 6379
+      DB_CONNECTION: mysql
+      DB_HOST: 127.0.0.1
+      DB_PORT: 3306
+      DB_DATABASE: helpers_test
+      DB_USERNAME: helpers
+      DB_PASSWORD: secret
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: dom, json, mbstring, pcntl, pdo_mysql, pdo_sqlite, redis
+          coverage: none
+
+      - name: Get Composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache Composer dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: composer-${{ matrix.laravel }}-${{ hashFiles('composer.json', 'composer.lock') }}
+          restore-keys: composer-${{ matrix.laravel }}-
+
+      - name: Install dependencies
+        run: |
+          composer install --no-interaction --prefer-dist
+          composer require --dev "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+          composer update orchestra/testbench --with-all-dependencies --no-interaction --prefer-dist
+
+      - name: Verify Laravel version
+        run: |
+          php -r "
+            require 'vendor/autoload.php';
+            \$app = require 'vendor/orchestra/testbench-core/laravel/bootstrap/app.php';
+            \$app->make('Illuminate\Contracts\Console\Kernel')->bootstrap();
+            echo \$app->version();
+          " | grep -E '^${{ matrix.laravel }}\.'
+
+      - name: Run full behavioral suite
+        run: vendor/bin/phpunit -c phpunit.ci.xml --testsuite HalaeiHelpers,Characterization
+
+      - name: Public API contract
+        run: vendor/bin/phpunit -c phpunit.ci.xml --testsuite Contract
+
+      - name: Comprehensive validation
+        run: vendor/bin/phpunit -c phpunit.ci.xml --testsuite Validation
+
+  coverage:
+    name: Coverage (min 95% gate)
+    runs-on: ubuntu-latest
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_DATABASE: helpers_test
+          MYSQL_USER: helpers
+          MYSQL_PASSWORD: secret
+          MYSQL_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 -uhelpers -psecret"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+
+    env:
+      REDIS_HOST: 127.0.0.1
+      REDIS_PORT: 6379
+      DB_CONNECTION: mysql
+      DB_HOST: 127.0.0.1
+      DB_PORT: 3306
+      DB_DATABASE: helpers_test
+      DB_USERNAME: helpers
+      DB_PASSWORD: secret
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: dom, json, mbstring, pcntl, pdo_mysql, pdo_sqlite, redis
+          coverage: pcov
+
+      - name: Install dependencies
+        run: |
+          composer install --no-interaction --prefer-dist
+          composer require --dev "orchestra/testbench:^11.0" --no-interaction --no-update
+          composer update orchestra/testbench --with-all-dependencies --no-interaction --prefer-dist
+
+      - name: Wait for MySQL
+        run: |
+          for i in $(seq 1 30); do
+            if php -r "
+              try {
+                  new PDO(
+                      'mysql:host=127.0.0.1;port=3306;dbname=helpers_test',
+                      'helpers',
+                      'secret'
+                  );
+                  exit(0);
+              } catch (Throwable \$e) {
+                  exit(1);
+              }
+            "; then
+              echo "MySQL is ready."
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "MySQL did not become ready in time."
+          exit 1
+
+      - name: Coverage gate
+        run: bash scripts/check-coverage.sh

.gitignore

@@ -1,4 +1,5 @@
 .idea
 /vendor
 /.phpunit.result.cache
-composer.lock
+/build
+composer.lock

README.md

@@ -1,11 +1,26 @@
 # Miscellaneous Helpers for PHP and Laravel
 
-[![Build Status](https://travis-ci.org/halaei/helpers.svg)](https://travis-ci.org/halaei/helpers)
+[![Tests](https://github.com/halaei/helpers/actions/workflows/tests.yml/badge.svg)](https://github.com/halaei/helpers/actions/workflows/tests.yml)
 [![Latest Stable Version](https://poser.pugx.org/halaei/helpers/v/stable)](https://packagist.org/packages/halaei/helpers)
 [![Total Downloads](https://poser.pugx.org/halaei/helpers/downloads)](https://packagist.org/packages/halaei/helpers)
 [![Latest Unstable Version](https://poser.pugx.org/halaei/helpers/v/unstable)](https://packagist.org/packages/halaei/helpers)
 [![License](https://poser.pugx.org/halaei/helpers/license)](https://packagist.org/packages/halaei/helpers)
 
+## Requirements
+
+| Version | PHP | Laravel |
+|---------|-----|---------|
+| **^2.0** | ^8.1 | 10, 11, 12, 13 |
+| ^0.9 / ^1.0 | 7.4+ | 8, 9 |
+
+```bash
+composer require halaei/helpers:^2.0
+```
+
+### Upgrading from v0.9 / v1.0
+
+v2.0 preserves the public API. Update `composer.json` to `^2.0` and ensure PHP 8.1+. If you use `db:restore-dump` or Redis locks with phpredis, no code changes are required — Flysystem 3 and phpredis compatibility are handled internally. See [docs/laravel-13-migration-plan.md](docs/laravel-13-migration-plan.md) for the full checklist.
+
 ## About this Package
 This is a collection of miscellanous utilities gathered in one package for you:
 - Supervisor: safely run a piece of code in an infinite loop.
@@ -253,7 +268,7 @@ while (! $lock->lock('critical_section', 0.1) {}
 // 2. Do some critical job
 //...
 // 3. Release the lock
-$lock->unlock('critical_section', 0.1);
+$lock->unlock('critical_section');
 ```
 
 ### Process
@@ -326,5 +341,44 @@ echo $crypt->encrypt(16, 0 /*no padding*/); // 89
 echo $crypt->decrypt('999989'); // 36
 ```
 
+## Testing
+
+### Local (Windows / macOS)
+
+Requires PHP 8.1+ and Composer. Uses SQLite by default; Redis, MySQL, `pcntl`, and Process tests are skipped via `phpunit.xml` groups.
+
+```bash
+composer install
+vendor/bin/phpunit
+```
+
+On Windows, use PHP 8.1+ from [Laravel Herd](https://herd.laravel.com/) or similar (`php84 vendor/bin/phpunit`).
+
+### Docker (full suite)
+
+Linux container with PHP 8.3, Redis 7, MySQL 8, `pcntl`, `pcov`, and the `unix` / `redis` test groups via `phpunit.docker.xml`.
+
+```bash
+docker compose run --rm test
+docker compose run --rm test --testsuite Contract
+docker compose run --rm test --coverage-text
+docker compose run --rm --entrypoint bash test scripts/check-coverage.sh
+```
+
+### CI
+
+GitHub Actions runs a **Laravel 10–13 matrix** (with Redis) plus a **coverage gate** (minimum 95%, configurable via `MIN_COVERAGE`) on PHP 8.3. Locally:
+
+```bash
+composer test:coverage   # requires Linux, pcov, Redis, MySQL (see docker compose)
+```
+
+| Service | Image | Purpose |
+|---------|-------|---------|
+| `test` | `docker/Dockerfile` | PHPUnit + Composer |
+| `redis` | `redis:7-alpine` | Redis lock tests |
+| `mysql` | `mysql:8.0` | `insertIgnore` macro tests |
+
+
 ## License
 This package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)