php-modernization

# PHP Modernization ## Agent contract 1. **Discover**: `uv run ${CLAUDE_SKILL_DIR}/scripts/introspect.py` (cheap), or `verify_php_project.py --summary` (full, with `agent_actions[]`). 2. **Drill**: `... --check PM-XX` per finding. Full output when triaging >3. 3. **Apply**: `uv run ${CLAUDE_SKILL_DIR}/scripts/modernize_loop.py --mode dry-run`. Review transcript before applying. 4. **References**: load on demand; do not pre-load. ## Reference routing | Need | Read | |---|---| | PHP 8.0-8.3 baseline | `references/php8-features.md` | | PHP 8.4 | `references/php-8.4.md` | | PHP 8.5 | `references/php-8.5.md` | | PSR / PER-CS | `references/psr-per-compliance.md` | | PHPStan config | `references/phpstan-compliance.md` | | Static analysis | `references/static-analysis-tools.md` | | PHP-CS-Fixer deprecations | `references/php-cs-fixer-deprecations.md` | | DTOs / VOs / inputs | `references/type-safety.md`, `references/request-dtos.md` | | Adapter / registry | `references/adapter-registry-pattern.md` | | Multi-version compat | `references/multi-version-adapters.md`, `references/composer-package-metadata.md` | | Symfony patterns | `references/symfony-patterns.md` | | PSR-15 middleware | `references/psr15-middleware-architecture.md` | | Doctrine edges | `references/doctrine-modernization-edges.md` | | API Platform | `references/api-platform-edges.md` | | Immutability | `references/immutability-boundaries.md` | | Contracts & invariants | `references/contracts-and-invariants.md` | | Mutation testing | `references/mutation-testing.md` | | Lexing PHP as tokens, across versions | `references/lexing-php-across-versions.md` | | Migration planning | `references/migration-strategies.md` | | Public API inventory vs consumers | `references/public-api-inventory.md` | | PHPUnit 12→13, mock vs stub | `references/phpunit-modernization.md` | | Multi-agent dispatch hazards | `references/multi-agent-pitfalls.md` | | Reading a PHP config file without running it | `references/reading-php-config-safely.md` | ## Hard guardrails - Never apply `readonly` to Doctrine entities or mapped-superclasses (embeddables: see `references/doctrine-modernization-edges.md`). - Never run Rector without `--dry-run`. Invoke `vendor/bin/rector` directly — composer script aliases can drop `--`-forwarded flags depending on configuration. - Never raise PHPStan level without regenerating + committing the baseline. Shrink, never delete. - Never apply blanket `final` to mock targets or extension points without confirmation. - Never edit `@generated` files or files under `var/cache/`, `vendor/`, `node_modules/`, `.Build/`. - Never `git checkout --` files outside your scope in shared trees — use `git stash` / `git diff`. - Never trust a warm PHPStan cache after vendor change: `rm -rf /tmp/phpstan-* var/cache/phpstan` first. - Never mass-substitute `createMock` → `createStub` — promote to `expects(...)->method(...)->with(...)`. ## Migration checklist - [ ] `declare(strict_types=1)` everywhere - [ ] `@PER-CS`, no deprecated aliases - [ ] PHPStan ≥9 (`treatPhpDocTypesAsCertain: false`); 10 for new - [ ] PHPat for layer boundaries - [ ] Return + parameter types on all methods - [ ] DTOs over arrays; backed enums over constants - [ ] PSR interfaces in type-hints - [ ] `#[Override]` (8.3+), `#[SensitiveParameter]` (8.2+), typed constants (8.3+) - [ ] readonly on DTOs/VOs/events only - [ ] Property hooks (8.4); `array_find/any/all` (8.4); pipe `|>` (8.5) - [ ] PHPUnit 12+: stubs use `createStub`, mocks `createMock` + `expects` (no `self::any()` in 13) - [ ] Rector `withComposerBased(symfony: true)` (per-version `SymfonySetList::SYMFONY_*` are `@deprecated`)