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
Migration planning	references/migration-strategies.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)