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

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)