Refactor: Complete Project Overhaul for Quality, Testing, and DX

.github/workflows/tests.yml

@@ -0,0 +1,51 @@
+# This is a GitHub Actions workflow file.
+# It defines a set of jobs that will be run automatically on every push or pull request
+# to the repository, ensuring code quality and preventing regressions.
+
+name: Run PHP Tests & Static Analysis
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    # The job will run on the latest version of Ubuntu.
+    runs-on: ubuntu-latest
+
+    # This strategy block defines a build matrix.
+    # FIX: The matrix now starts from PHP 8.2, which is the minimum version
+    # required by the project's locked dependencies (PHPUnit 11).
+    strategy:
+      matrix:
+        php-version: ['8.2', '8.3']
+
+    steps:
+      # Step 1: Check out the repository code.
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # Step 2: Set up the PHP environment for the current job.
+      - name: Setup PHP v${{ matrix.php-version }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: dom, mbstring
+          coverage: xdebug
+
+      # Step 3: Install Composer dependencies using the lock file.
+      # This will now work consistently across all jobs in the matrix.
+      - name: Install Composer dependencies
+        run: composer install --prefer-dist --no-progress --no-suggest
+
+      # Step 4: Run the PHPUnit test suite.
+      - name: Run tests
+        run: ./vendor/bin/phpunit
+
+      # Step 5: Run PHPStan for static analysis (only on the latest PHP version).
+      - name: Run static analysis
+        if: matrix.php-version == '8.3'
+        run: ./vendor/bin/phpstan analyse src tests --level=8
+
+      # Step 6: Check for coding style violations (only on the latest PHP version).
+      - name: Check coding style
+        if: matrix.php-version == '8.3'
+        run: composer cs

.gitignore

@@ -1,57 +1,99 @@
-# JetBrains IDE
-.idea/
-*.iml
-
-# Eclipse
-.buildpath
-.project
-.settings
-
-# VI
-*.swp
+# # # # # # # # # # # # # # # # # #
+#       GENERATED BY ImNotJavad   #
+# # # # # # # # # # # # # # # # # #
 
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.cache
-nosetests.xml
-coverage.xml
+# ----------------------------------------------------------------
+# Composer - PHP Dependency Manager
+# ----------------------------------------------------------------
+# The vendor directory contains all third-party code. It should be installed via `composer install`.
+/vendor/
+# The composer.lock file locks the dependencies to specific versions.
+# While some teams commit this file, it's often ignored in libraries to allow more flexibility.
+# For applications, it's recommended to commit this file.
+# composer.lock
 
-# Sphinx documentation
-docs/_build/
 
-# emacs auto-saving files
-\#*#
-.#*#
-
-# composer
-vendor
-composer.lock
+# ----------------------------------------------------------------
+# Build & Test Artifacts
+# ----------------------------------------------------------------
+# Directory for PHPUnit code coverage reports.
+/coverage/
+# Build artifacts for PHAR archives.
 *.phar
-phar7
-phar5
-.phpunit.result.cache
+# Directory for any other build output.
+/build/
 
-# Vscode
-.vscode/*
-!.vscode/settings.json
-!.vscode/extensions.json
 
-# Cache
+# ----------------------------------------------------------------
+# Caching
+# ----------------------------------------------------------------
+# Cache file for PHPUnit.
+.phpunit.cache
+/.phpunit.cache/
+# Cache file for PHP CS Fixer.
 .php-cs-fixer.cache
-.phpdoc_cache
-*bak
+# Cache for static analysis tools like PHPStan or Psalm.
+.phpstan.cache
+.psalm.cache
+
 
-# ENV
+# ----------------------------------------------------------------
+# Environment Files
+# ----------------------------------------------------------------
+# Environment files contain sensitive data like API keys and database credentials.
+# They should NEVER be committed to version control. A `.env.example` file
+# should be committed instead as a template.
 .env
+.env.local
+.env.*.local
+# But track the example file.
+!/.env.example
+
+
+# ----------------------------------------------------------------
+# IDE & Editor Configuration
+# ----------------------------------------------------------------
+# These files are specific to a developer's local environment.
+.idea/
+.vscode/
+*.sublime-project
+*.sublime-workspace
+nbproject/
+# Temporary/swap files from editors like Vim.
+*.swp
+*.swo
+*~
+
+
+# ----------------------------------------------------------------
+# Operating System Files
+# ----------------------------------------------------------------
+# macOS specific files.
+.DS_Store
+.AppleDouble
+.LSOverride
+# Windows specific files.
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+
+# ----------------------------------------------------------------
+# Log & Temporary Files
+# ----------------------------------------------------------------
+# Any file ending in .log.
+*.log
+# Temporary files directory.
+/tmp/
+
 
-app_test.json
-app.json
-config.json
-/Dockerfile
-/docker-compose.yml
-/Caddyfile
-/changelog
+# ----------------------------------------------------------------
+# Node.js Dependencies (if used for front-end assets)
+# ----------------------------------------------------------------
+/node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+package-lock.json
+yarn.lock
 
-# Project

.php-cs-fixer.dist.php

@@ -1,9 +1,19 @@
 <?php
 
+// This configuration uses the "amphp/php-cs-fixer-config" package,
+// which provides a standard, modern coding style for PHP projects.
+// It helps maintain consistency across the entire codebase.
+
 $config = new Amp\CodeStyle\Config;
 $config->getFinder()
-    ->in(__DIR__ . "/src");
+    ->in(__DIR__ . "/src")
+    ->in(__DIR__ . "/tests");
 
 $config->setCacheFile(__DIR__ . '/.php-cs-fixer.cache');
 
+// FIX: Allow running on unsupported PHP versions (like PHP 8.4+).
+// The tool may not be fully compatible with the newest syntax, but this
+// setting is necessary to allow development on newer PHP runtimes.
+$config->setUnsupportedPhpVersionAllowed(true);
+
 return $config;