netresearch/php-modernization-skill

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.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/netresearch/php-modernization-skill --skill php-modernization

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

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[]). Then read the project's own commands — composer.json scripts, Makefile, DDEV/Docker wrappers, CI config. They fix the runtime, the config and the paths; use them over a bare vendor/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.
  2. Drill: ... --check PM-XX per finding. Full output when triaging >3. The verifier does not evaluate llm_review checkpoints (step 4): no result for one is no pass.
  3. 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.
ConcernTool (the one the project has)
PHP refactoringRector (+ TYPO3/Symfony sets)
Fluid, TypoScript, FlexForm/XML, YAML migrationFractor — not for PHP code
Types, match completeness (match.unhandled), version floor (phpVersion)PHPStan
Coding standardPHPCS/PHPCBF or PHP-CS-Fixer — whichever is configured
Syntaxphp -l / the project's lint, under the lowest supported PHP
BehaviourPHPUnit (the project's suite)
Test strength on the changed linesInfection, where installed
  1. 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_review checkpoints in checkpoints.yaml (enums PM-21, PHP 8 features and match PM-22, readonly PM-40, …) are yours; a green verifier does not cover them.

  1. Apply in bounded steps: baseline tests → modernize_loop.py --mode dry-run or rector 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.
  2. References: load on demand; do not pre-load.

Reference routing

NeedRead
PHP 8.0-8.3 baselinereferences/php8-features.md
PHP 8.4references/php-8.4.md
PHP 8.5references/php-8.5.md
PSR / PER-CSreferences/psr-per-compliance.md
PHPStan configreferences/phpstan-compliance.md
Static analysisreferences/static-analysis-tools.md
PHP-CS-Fixer deprecationsreferences/php-cs-fixer-deprecations.md
DTOs / VOs / inputsreferences/type-safety.md, references/request-dtos.md
Adapter / registryreferences/adapter-registry-pattern.md
Multi-version compatreferences/multi-version-adapters.md, references/composer-package-metadata.md
Symfony patternsreferences/symfony-patterns.md
PSR-15 middlewarereferences/psr15-middleware-architecture.md
Doctrine edgesreferences/doctrine-modernization-edges.md
API Platformreferences/api-platform-edges.md
Immutabilityreferences/immutability-boundaries.md
Contracts & invariantsreferences/contracts-and-invariants.md
Mutation testingreferences/mutation-testing.md
Lexing PHP as tokens, across versionsreferences/lexing-php-across-versions.md
Migration planningreferences/migration-strategies.md
Public API inventory vs consumersreferences/public-api-inventory.md
PHPUnit 12→13, mock vs stubreferences/phpunit-modernization.md
Multi-agent dispatch hazardsreferences/multi-agent-pitfalls.md
Reading a PHP config file without running itreferences/reading-php-config-safely.md

Hard guardrails

  • Never apply readonly to Doctrine entities or mapped-superclasses (embeddables: see references/doctrine-modernization-edges.md).
  • Never apply Rector (or modernize_loop.py --mode apply --confirm) before a --dry-run of the same scope and a review of its diff. Rector diffs can change behaviour (loose switch → strict match, readonly over mutable members). Pass --dry-run on 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 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 /tmp/phpstan-* var/cache/phpstan first. PHPStan and Rector caches outlive git worktree remove (references/multi-agent-pitfalls.md, Hazard 9).
  • PHP's default memory_limit is 128M; PHPStan stops at it on larger projects ("reached configured PHP memory limit"). Pass --memory-limit=1G.
  • 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 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, mocks createMock + expects (no self::any() in 13)
  • [ ] Rector withComposerBased(symfony: true) (per-version SymfonySetList::SYMFONY_* are @deprecated)