php-modernization

PHP 现代化

Agent 契约

1. 发现：运行 uv run ${CLAUDE_SKILL_DIR}/scripts/introspect.py（开销低），或运行 verify_php_project.py --summary（完整输出，包含 agent_actions[]）。
2. 深入检查：针对每项发现运行 ... --check PM-XX。排查超过 3 项时查看完整输出。
3. 应用：运行 uv run ${CLAUDE_SKILL_DIR}/scripts/modernize_loop.py --mode dry-run。应用前先检查执行记录。
4. 参考资料：按需加载；不要预先加载。

参考资料路由

需求	阅读
PHP 8.0-8.3 基线	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 配置	references/phpstan-compliance.md
静态分析	references/static-analysis-tools.md
PHP-CS-Fixer 弃用项	references/php-cs-fixer-deprecations.md
DTO / VO / 输入	references/type-safety.md、references/request-dtos.md
适配器 / 注册表	references/adapter-registry-pattern.md
多版本兼容性	references/multi-version-adapters.md、references/composer-package-metadata.md
Symfony 模式	references/symfony-patterns.md
PSR-15 中间件	references/psr15-middleware-architecture.md
Doctrine 注意事项	references/doctrine-modernization-edges.md
API Platform	references/api-platform-edges.md
不可变性	references/immutability-boundaries.md
契约与不变量	references/contracts-and-invariants.md
变异测试	references/mutation-testing.md
将 PHP 按令牌进行跨版本词法分析	references/lexing-php-across-versions.md
迁移规划	references/migration-strategies.md
公共 API 清单与使用方	references/public-api-inventory.md
PHPUnit 12→13、mock 与 stub	references/phpunit-modernization.md
多 Agent 调度风险	references/multi-agent-pitfalls.md
不运行 PHP 配置文件也能读取它	references/reading-php-config-safely.md

严格防护措施

• 切勿对 Doctrine 实体或映射超类应用 readonly（嵌入对象请参见 references/doctrine-modernization-edges.md）。
• 切勿在没有 --dry-run 的情况下运行 Rector。直接调用 vendor/bin/rector——根据配置，composer 脚本别名可能会丢弃通过 -- 转发的标志。
• 提升 PHPStan 级别前，务必重新生成并提交基线。只能缩减，绝不能删除。
• 未经确认，切勿对 mock 目标或扩展点一概应用 final。
• 切勿编辑 @generated 文件或 var/cache/、vendor/、node_modules/、.Build/ 下的文件。
• 在共享目录树中，切勿对范围之外的文件运行 git checkout --——请使用 git stash / git diff。
• 更改 vendor 后，切勿信任未清理的 PHPStan 缓存：先运行 rm -rf /tmp/phpstan-* var/cache/phpstan。
• 切勿批量替换 createMock → createStub——应改用 expects(...)->method(...)->with(...)。

迁移清单

• 所有位置都添加 declare(strict_types=1)
• 使用 @PER-CS，不使用已弃用的别名
• PHPStan ≥9（treatPhpDocTypesAsCertain: false）；新项目使用 10
• 使用 PHPat 检查分层边界
• 所有方法都声明返回类型和参数类型
• 使用 DTO 而非数组；使用有底层值的枚举而非常量
• 类型提示使用 PSR 接口
• 使用 #[Override]（8.3+）、#[SensitiveParameter]（8.2+）、类型化常量（8.3+）
• 仅对 DTO / VO / 事件使用 readonly
• 属性钩子（8.4）；array_find/any/all（8.4）；管道运算符 |>（8.5）
• PHPUnit 12+：存根使用 createStub，mock 使用 createMock + expects（13 中不使用 self::any()）
• Rector 使用 withComposerBased(symfony: true)（按版本区分的 SymfonySetList::SYMFONY_* 已标记为 @deprecated）