企业官网建设流程全解析

PHP 8.4 升级不踩坑：Rector 自动重构快速指南

【免费下载链接】rectorInstant Upgrades and Automated Refactoring of any PHP 5.3+ code项目地址: https://gitcode.com/GitHub_Trending/re/rector

把项目升到 PHP 8.4 之后，报错列表里最扎眼的往往不是新语法，而是一串E_DEPRECATED和类型相关的告警。手动翻几百个文件既慢又容易漏。Rector 就是干这活的：装上它，跑两条命令，十几分钟完成整个项目的 PHP 8.4 适配。这篇文章讲清楚要改什么、怎么装、怎么跑、怎么验证。

先看清单：PHP 8.4 适配到底要改哪些代码

重写方法：补上 #[\Override] 属性

子类重写父类方法时，方法签名前要标#[\Override]，缺了它升级后就是一片弃用提示。大型项目里这类方法动辄上百个，逐个手工添加基本不现实。Rector 的规则会分析类继承关系，只在真正重写了父类方法的地方插入属性，不碰普通方法。

数组类型提示：从 array 细化到 array

8.4 的类型检查更严，模糊的array提示最好改成具体形状，比如array<User>。Rector 能根据代码里对数组元素实际怎么用，把这类提示自动细化出来，省掉人工逐行推断。

class PostRepository { - public function fetchPosts(): array + public function fetchPosts(): array<Post> { return $this->posts; } }

这些改动单看都不难，难在量大、还依赖上下文判断：加错一个属性、把不该动的类型改了，都会引入新 bug。Rector 的做法是把代码解析成抽象语法树（AST），在节点层面判断和替换，再配合预览模式兜底，所以可以放心地批量跑。

准备工作：两条命令装好 Rector

第一条，装到开发依赖里：

composer require rector/rector --dev

第二条，生成配置文件：

vendor/bin/rector init

命令会在项目根目录创建rector.php，核心就两行：

return RectorConfig::configure() ->withPaths([__DIR__ . '/src']) ->withPreparedSets(php84: true);

withPaths指定要扫描哪些目录，withPreparedSets(php84: true)启用官方维护的 PHP 8.4 适配规则集，其余规则集默认关闭，想再加随时开启。

跑起来：先 dry-run 预览，再正式执行

预览：

vendor/bin/rector process --dry-run

输出长这样，每个文件的具体改动一目了然：

[OK] Rector is done! 12 files would have changed (dry-run)

确认改动符合预期后，正式执行：

vendor/bin/rector process

跑完验证三件事：

1. 跑一遍单元测试，确认行为没变；
2. 在 PHP 8.4 环境里复跑关键流程，确认E_DEPRECATED不再出现；
3. 看 Rector 的汇总输出，核对改动文件数和你的预期是否一致。

进阶控制：跳过指定文件、注入自定义规则

两个配置项够用：

• withSkip：不想被改的目录或文件直接排除；
• withRules：规则集没覆盖的自定义需求，注入自己的规则类。

->withSkip([ __DIR__ . '/src/Generated', ])

另外建议把 Rector 接进 CI/CD 定期跑，dry-run 模式下发现回归直接提示，PHP 8.4 的适配就不用一次性扛完。

完整规则清单见 README.md，8.4 规则的具体实现在 rules/Php84/Rector/。把机械劳动交给工具，你只管业务。

【免费下载链接】rectorInstant Upgrades and Automated Refactoring of any PHP 5.3+ code项目地址: https://gitcode.com/GitHub_Trending/re/rector