php-modernization
Use when modernizing PHP code: PHP 8.1-8.5 features, PSR/PHP-FIG/PER-CS compliance, PHPStan/Rector/PHP-CS-Fixer/PHPat tooling, DTOs/enums/readonly/property hooks, type safety. Triggers: PHP modernization, type safety, PHPStan, Rector, PHP-CS-Fixer, enum, DTO, readonly, strict_types, property hooks, PHP 8.4, PHP 8.5.
How do I install this agent skill?
npx skills add https://github.com/netresearch/php-modernization-skill --skill php-modernizationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a comprehensive toolkit for modernizing PHP codebases. It performs static analysis and orchestration of local PHP tools. While it executes shell commands and processes untrusted source code, these activities are consistent with its primary purpose and follow best practices for the AI agent environment.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 1 issue
- Runlayerpass
2/13 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
PHP Modernization
Agent contract
-
Discover:
uv run ${CLAUDE_SKILL_DIR}/scripts/introspect.py(cheap), orverify_php_project.py --summary(full, withagent_actions[]). Then read the project's own commands —composer.jsonscripts,Makefile, DDEV/Docker wrappers, CI config. They fix the runtime, the config and the paths; use them over a barevendor/bin/*call. Exception: when you must add a flag (--dry-run,--only, a path), run the command the script wraps with the flag written out, in the same runtime — Composer aliases can drop---forwarded flags. -
Drill:
... --check PM-XXper finding. Full output when triaging >3. The verifier does not evaluatellm_reviewcheckpoints (step 4): no result for one is no pass. -
Use the project's tools, and run them. Naming a tool is not using it. A check you did not run is reported as not run.
Concern Tool (the one the project has) PHP refactoring Rector (+ TYPO3/Symfony sets) Fluid, TypoScript, FlexForm/XML, YAML migration Fractor — not for PHP code Types, matchcompleteness (match.unhandled), version floor (phpVersion)PHPStan Coding standard PHPCS/PHPCBF or PHP-CS-Fixer — whichever is configured Syntax php -l/ the project's lint, under the lowest supported PHPBehaviour PHPUnit (the project's suite) Test strength on the changed lines Infection, where installed -
Decide what the tools cannot. Before each change, answer from callers, data flow and tests:
- Which intent becomes clearer?
- Which observable behaviour must stay (return values, comparisons, exceptions, stored and external values, public signatures)?
- Which existing rule or tool makes the change?
- Which check shows the result is right — and which behaviour test pins the decision?
The verifier runs mechanical checks only. The
llm_reviewcheckpoints incheckpoints.yaml(enums PM-21, PHP 8 features andmatchPM-22,readonlyPM-40, …) are yours; a green verifier does not cover them. -
Apply in bounded steps: baseline tests →
modernize_loop.py --mode dry-runorrector process <path> --only=<rule> --dry-run(when the project's own command adds a config or a container, run that command with the flags instead: the orchestrator calls the binaries directly) → review the diff against step 4 → apply → formatter → lint, PHPStan, tests → the same dry-run again proposes nothing → commit. Details:references/migration-strategies.md. -
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, interface changes on update | 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
readonlyto Doctrine entities or mapped-superclasses (embeddables: seereferences/doctrine-modernization-edges.md). - Never apply Rector (or
modernize_loop.py --mode apply --confirm) before a--dry-runof the same scope and a review of its diff. Rector diffs can change behaviour (looseswitch→ strictmatch,readonlyover mutable members). Pass--dry-runon the Rector command itself (the one the project's script runs, in its runtime), never through a Composer alias with--: depending on the configuration the alias drops it. - 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 /tmp/phpstan-* var/cache/phpstanfirst. PHPStan and Rector caches outlivegit worktree remove(references/multi-agent-pitfalls.md, Hazard 9). - PHP's default
memory_limitis 128M; PHPStan stops at it on larger projects ("reached configured PHP memory limit"). Pass--memory-limit=1G. - 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 for closed value sets (open sets stay validated strings)
- 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)
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/netresearch/php-modernization-skill/php-modernization">View php-modernization on skillZs</a>