netresearch PHP Modernization
Agent contract
- Discover:
uv run ${CLAUDE_SKILL_DIR}/scripts/introspect.py(cheap), orverify_php_project.py --summary(full, withagent_actions[]). - Drill:
... --check PM-XXper finding. Full output when triaging >3. - Apply:
uv run ${CLAUDE_SKILL_DIR}/scripts/modernize_loop.py --mode dry-run. Review transcript before applying. - 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
readonlyto Doctrine entities or mapped-superclasses (embeddables: seereferences/doctrine-modernization-edges.md). - Never run Rector without
--dry-run. Invokevendor/bin/rectordirectly — 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
finalto mock targets or extension points without confirmation. - Never edit
@generatedfiles or files undervar/cache/,vendor/,node_modules/,.Build/. - Never
git checkout --files outside your scope in shared trees — usegit stash/git diff. - Never trust a warm PHPStan cache after vendor change:
rm -rf /tmp/phpstan-* var/cache/phpstanfirst. - Never mass-substitute
createMock→createStub— promote toexpects(...)->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, mockscreateMock+expects(noself::any()in 13) - Rector
withComposerBased(symfony: true)(per-versionSymfonySetList::SYMFONY_*are@deprecated)