Modernizes PHP codebases by implementing newer language features, improving type safety, and ensuring compliance with PSR and PER-CS standards.
- GitHub stars
- 63
- Files
- 33
- Last commit
- Nov 9, 2026
- License
- See LICENSE
- Allowed tools
- 9
What does the php-modernization skill do?
php-modernization modernizes PHP codebases by implementing newer language features, improving type safety, and ensuring compliance with PSR and PER-CS standards.
Summary generated from the skill's SKILL.md.
About the php-modernization skill
Updating legacy PHP codebases to modern standards is the primary function of this skill. It helps developers implement features from PHP 8.1 through PHP 8.5, such as property hooks, enums, and readonly properties, while ensuring strict type safety. An agent should load this skill when tasked with refactoring code for PSR or PER-CS compliance, migrating to newer PHP versions, or improving static analysis results.
The skill utilizes specialized tools including Rector, PHPStan, PHP-CS-Fixer, and PHPat to automate and verify changes. It relies on a structured workflow involving discovery through introspection scripts, detailed drilling into specific findings, and a modernization loop that supports dry-run modes for safe review. To function, the environment requires uv, PHP 8.1 or later, and Composer. It provides specific guidance on handling complex scenarios like Doctrine entities, Symfony patterns, and PHPUnit migrations to prevent common architectural errors during the refactoring process.
What an agent can do with it
- 1Improve type safetyRefactor arrays into Data Transfer Objects and replace constants with backed enums to strengthen the type system.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the php-modernization skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the php-modernization skill in Claude Code
~/.claude/skills/php-modernization/SKILL.md
$ npx degit netresearch/php-modernization-skill/skills/php-modernization ~/.claude/skills/php-modernizationInstall the php-modernization skill in Claude Code (project)
.claude/skills/php-modernization/SKILL.md
$ npx degit netresearch/php-modernization-skill/skills/php-modernization .claude/skills/php-modernizationInstall the php-modernization skill in Codex
~/.agents/skills/php-modernization/SKILL.md
$ npx degit netresearch/php-modernization-skill/skills/php-modernization ~/.agents/skills/php-modernizationInstall the php-modernization skill in Gemini CLI
~/.gemini/skills/php-modernization/SKILL.md
$ npx degit netresearch/php-modernization-skill/skills/php-modernization ~/.gemini/skills/php-modernizationInstall the php-modernization skill in Claude.ai
npx degit netresearch/php-modernization-skill/skills/php-modernization php-modernization && zip -r php-modernization.zip php-modernization # claude.ai → Customize → Skills → + → Create skill → Upload a skill → php-modernization.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablenetresearch/php-modernization-skill/skills/php-modernization is public and reachablegithub.com/netresearch/php-modernization-skill/tree/HEAD/ski ↗Pass
- Open source license (OSI)License named in a file, not as an SPDX idNot checked
- Commit or release in the last yearLast commit 2026-11-09github.com/netresearch/php-modernization-skill/commits ↗Pass
- No download-and-run or credential theft in scripts5 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/netresearch/php-modernization-skill/blob/HEAD/ski ↗Pass
- Pre-approved tools are scopedPre-approved: Bash(php:*), Bash(composer:*), Bash(uv:*), Bash(vendor/bin/*), Bash(.Build/bin/*), Read, …github.com/netresearch/php-modernization-skill/blob/HEAD/ski ↗Pass
SKILL.md
View on GitHubPHP 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 |
| 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
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)
Files in this skill
33php-modernization skill questions
How do I install the php-modernization skill in Claude Code?
Run npx degit netresearch/php-modernization-skill/skills/php-modernization ~/.claude/skills/php-modernization. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the php-modernization skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What are the compatibility requirements for this skill?
The skill requires PHP 8.1 or later, Composer, and uv (which runs scripts on Python 3.11 or later).
Are there restrictions on using the readonly modifier?
Yes, you should never apply readonly to Doctrine entities or mapped-superclasses; it should only be applied to DTOs, VOs, and events.
How should Rector be executed to avoid unintended changes?
You should never run Rector without using the --dry-run flag and should invoke the vendor binary directly to ensure flags are forwarded correctly.