Merge 1.x into main

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: PHPUnit (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - '8.2'
+          - '8.3'
+          - '8.4'
+          - '8.5'
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate Composer configuration
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist
+
+      - name: Audit dependencies
+        run: composer audit
+
+      - name: Run PHPUnit
+        run: composer test
+
+  quality:
+    name: Static analysis and formatting
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate Composer configuration
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist
+
+      - name: Check formatting
+        run: composer format:check
+
+      - name: Run PHPStan
+        run: composer analyze:phpstan
+
+      - name: Run Psalm
+        run: composer analyze:psalm
+
+  coverage:
+    name: PHPUnit coverage (PHP 8.5)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP with Xdebug
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+          coverage: xdebug
+          tools: composer:v2
+
+      - name: Validate Composer configuration
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist
+
+      - name: Run PHPUnit with coverage
+        run: composer test:coverage
+
+      - name: Upload HTML coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpunit-coverage-report
+          path: build/coverage/
+          if-no-files-found: error
+          retention-days: 14

.gitignore

@@ -0,0 +1,5 @@
+/vendor/
+/node_modules/
+/build/
+/.phpunit.cache/
+.php-cs-fixer.cache

.php-cs-fixer.dist.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpCsFixer\Config;
+use PhpCsFixer\Finder;
+
+return (new Config())
+    ->setRiskyAllowed(false)
+    ->setRules([
+        '@PSR12' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'ordered_imports' => ['sort_algorithm' => 'alpha'],
+        'no_unused_imports' => true,
+        'not_operator_with_successor_space' => true,
+        'trailing_comma_in_multiline' => ['elements' => ['arrays']],
+        'phpdoc_scalar' => true,
+        'unary_operator_spaces' => true,
+        'binary_operator_spaces' => true,
+        'blank_line_before_statement' => [
+            'statements' => ['break', 'continue', 'declare', 'return', 'throw', 'try'],
+        ],
+    ])
+    ->setFinder(
+        (new Finder())
+            ->in(__DIR__ . '/src')
+            ->in(__DIR__ . '/tests')
+    );

CONTRIBUTING.md

@@ -0,0 +1,150 @@
+# Contributing
+
+TD-PHP is a generic PHP project skeleton focused on test-driven development and a small, explicit quality baseline.
+
+## Development environment
+
+Requirements:
+
+- PHP 8.2+
+- Composer 2.x
+
+Install dependencies:
+
+```bash
+composer install
+```
+
+## The development loop
+
+For behaviour changes, prefer a test-first workflow:
+
+1. Describe the required behaviour with a test.
+2. Run the test and confirm that it fails for the expected reason.
+3. Implement the smallest change needed to make it pass.
+4. Refactor without changing the behaviour.
+5. Run the complete quality gate.
+
+The important part is not the ceremony. The important part is that the test describes behaviour before the implementation becomes the source of truth.
+
+## Verification
+
+Run the complete local check with:
+
+```bash
+composer check-all
+```
+
+This verifies:
+
+1. PHP formatting.
+2. PHPStan.
+3. Psalm.
+4. PHPUnit.
+
+To run individual checks:
+
+```bash
+composer test
+composer analyze:phpstan
+composer analyze:psalm
+composer format:check
+```
+
+To apply PHP CS Fixer formatting:
+
+```bash
+composer format
+```
+
+After formatting, run `composer check-all` again.
+
+## Tests
+
+Production code belongs in `src/`. Tests belong in `tests/`.
+
+Use PHPUnit for automated tests. Keep tests deterministic and focused on observable behaviour.
+
+Prefer:
+
+- small tests with one clear reason to fail;
+- explicit inputs and outputs;
+- isolated unit tests where possible;
+- integration tests when integration itself is the behaviour under test.
+
+Avoid coupling tests to implementation details unless the implementation detail is itself part of the contract being verified.
+
+Coverage is useful for finding untested areas, but TD-PHP does not treat a coverage percentage as a substitute for test quality.
+
+## Static analysis
+
+Both PHPStan and Psalm are part of the baseline.
+
+New production code should pass both analysers. Do not add broad suppressions simply to make the checks green.
+
+When a warning identifies a real design or typing problem, prefer fixing the underlying code. If a suppression is genuinely necessary, keep it narrow and document why.
+
+## Formatting
+
+PHP CS Fixer is the formatting tool for this repository.
+
+Use:
+
+```bash
+composer format
+```
+
+to apply formatting, and:
+
+```bash
+composer format:check
+```
+
+to verify formatting without modifying files.
+
+Avoid unrelated formatting changes in a functional change.
+
+## Project structure
+
+Keep the top-level structure conventional:
+
+```text
+src/       production PHP
+tests/     automated tests
+```
+
+Start with `tests/Unit/` when unit tests are appropriate. Add other test categories only when the project needs them.
+
+Do not introduce framework-specific directories or infrastructure into the skeleton itself.
+
+## Dependencies and tooling
+
+The baseline intentionally contains four development tools:
+
+- PHPUnit
+- PHPStan
+- Psalm
+- PHP CS Fixer
+
+Do not add another testing or analysis tool merely because it is popular. Add infrastructure only when the project has a demonstrated need for it.
+
+Likewise, do not remove one of the baseline tools without an explicit decision to change TD-PHP's purpose.
+
+## Pull requests
+
+A good change should:
+
+- solve one coherent problem;
+- keep the change as small as practical;
+- include or update tests when behaviour changes;
+- preserve compatibility unless a breaking change is intentional;
+- keep the skeleton generic;
+- update documentation when the development workflow changes.
+
+Before opening a pull request, run:
+
+```bash
+composer check-all
+```
+
+Then review the final diff for generated files, accidental dependencies, and unrelated changes.