实际问题：PHP 项目升级与代码规范的“老大难”
随着 php 版本的快速迭代，我们享受着新特性带来的便利，但也面临着旧项目升级的巨大挑战。手动修改废弃语法、调整函数调用、适配新的类型声明……这不仅工作量巨大，而且稍有不慎就可能引入新的 bug。尤其是在大型项目中，这种“体力活”更是让人望而却步。
除了版本升级，代码规范也是一个永恒的话题。每个开发者都有自己的编码习惯，当这些习惯汇聚到一个项目中时，代码风格的差异就会显现出来：有的用空格，有的用 Tab；有的喜欢长行，有的偏爱短行；甚至命名规范也可能五花八门。这不仅降低了代码的可读性，也增加了代码审查的难度和团队协作的摩擦。
我曾尝试过各种方法来解决这些问题：手动查找替换、编写简单的脚本，甚至依赖人工 Code Review。但这些方法效率低下，容易遗漏，并且无法从根本上解决问题。我需要一个更智能、更自动化的工具。
解决方案：Rector 与 eliashaeussler/rector-config
的强强联合
在一番探索之后，我发现了 Rector。它是一个强大的 PHP 代码静态分析和重构工具，能够自动执行大量的代码转换任务，包括：
- 版本升级： 自动将代码从旧的 PHP 版本升级到新的版本，处理废弃函数、语法糖等。
- 代码规范： 按照 PSR 标准或其他自定义规则自动格式化代码。
- 重构模式： 应用各种设计模式和最佳实践，优化代码结构。
然而，Rector 的强大也伴随着其配置的复杂性。
rector.php配置文件中包含了大量的规则集和选项，对于初学者来说，配置一个符合自己项目需求的 Rector 可能需要花费不少时间。
立即学习“PHP免费学习笔记（深入）”；
这时，
eliashaeussler/rector-config这个 Composer 包进入了我的视野。它并非一个全新的重构工具，而是 Rector 的一个个人化、高度封装的配置集合。作者将自己在多个项目中使用 Rector 的经验总结成一套开箱即用的配置，大大简化了
rector.php的编写过程。虽然作者明确指出这是其个人配置，不提供外部支持，但对于许多有类似需求的开发者来说，它无疑提供了一个极佳的起点和范例。
如何使用 Composer 引入并应用 eliashaeussler/rector-config
使用 Composer 引入
eliashaeussler/rector-config非常简单，因为它是一个开发依赖：
composer require --dev eliashaeussler/rector-config
安装完成后，你就可以在项目的
rector.php配置文件中利用它来快速搭建 Rector 环境了。下面是一个典型的
rector.php配置示例，展示了
eliashaeussler/rector-config的强大之处：
// rector.php
use EliasHaeussler\RectorConfig\Config\Config;
use EliasHaeussler\RectorConfig\Set\CustomSet;
use Rector\Config\RectorConfig;
use Rector\Php80\Rector\Class_\AnnotationToAttributeRector;
use Rector\Set\ValueObject\SetList;
use Rector\ValueObject\PhpVersion;
return static function (RectorConfig $rectorConfig): void {
// 1. 可选：明确配置 PHP 版本，Rector 会根据此版本进行转换
// 如果不设置，Rector 会使用当前环境的 PHP 版本
$phpVersion = PhpVersion::PHP_81;
// 2. 创建配置对象，并指定需要扫描的目录
$config = Config::create($rectorConfig, $phpVersion)->in(
__DIR__.'/src', // 扫描 src 目录
__DIR__.'/tests', // 扫描 tests 目录
);
// 3. 排除不需要扫描的特定路径
$config->not(
__DIR__.'/src/lib', // 排除 src/lib 目录
__DIR__.'/tests/test-application/vendor', // 排除测试应用中的 vendor 目录
);
// 4. 包含常用的框架/库特定的 Rector 规则集
$config->withPHPUnit(); // 包含 PHPUnit 相关的升级和规范规则
$config->withSymfony(); // 包含 Symfony 框架相关的规则
$config->withTYPO3(); // 包含 TYPO3 框架相关的规则
// 5. 包含自定义的通用规则集
$config->withSets(
new CustomSet(
SetList::CODE_QUALITY, // 包含代码质量提升规则
SetList::CODING_STYLE, // 包含编码风格规范规则
),
);
// 6. 跳过特定的 Rector 规则或文件
$config->skip(
AnnotationToAttributeRector::class, // 跳过将注解转换为属性的 Rector 规则
[
__DIR__.'/src/Some/File.php', // 跳过特定文件的处理
],
);
// 7. 应用所有配置
$config->apply();
};代码解析：
-
Config::create($rectorConfig, $phpVersion)
: 这是核心，它使用eliashaeussler/rector-config
提供的Config
类来初始化 Rector 的配置对象。你可以指定目标 PHP 版本，让 Rector 知道如何进行版本升级相关的转换。 -
->in()
和->not()
: 明确指定 Rector 应该扫描哪些目录，以及跳过哪些目录。这对于大型项目或只希望处理部分代码的情况非常有用。 -
->withPHPUnit()
,->withSymfony()
,->withTYPO3()
: 这是eliashaeussler/rector-config
的亮点之一。它封装了针对这些流行框架和库的常用 Rector 规则集，让你无需手动查找和添加，只需一行代码即可启用。 -
->withSets(new CustomSet(...))
: 即使有了预设的规则集，你仍然可以灵活地添加 Rector 提供的其他通用规则集，例如CODE_QUALITY
和CODING_STYLE
，进一步提升代码质量和统一风格。 -
->skip()
: 提供了精细控制，允许你跳过某些特定的 Rector 规则，或者排除特定文件不被处理，以应对特殊情况。 -
->apply()
: 最后一步，将所有配置应用到 Rector 实例中。
通过这种方式，原本可能需要几十甚至上百行手动配置的
rector.php文件，现在被精简成了易读、易维护的几行代码，并且功能更加强大和灵活。
优势与实际应用效果
- 自动化升级，告别手动苦役： 借助 Rector 及其预设的规则，我的项目从 PHP 7.4 升级到 8.1 变得异常顺利。大部分语法转换、废弃函数替换都由工具自动完成，我只需要关注少量无法自动处理的逻辑变更，大大节省了时间和精力。
-
统一代码规范，提升团队协作效率： 通过在 CI/CD 流程中集成 Rector，并使用
eliashaeussler/rector-config
统一配置，所有提交的代码都能自动按照预设的风格进行格式化和优化。这不仅减少了 Code Review 中的风格争议，也让新成员能更快地融入团队，因为他们面对的是一个高度统一、易于理解的代码库。 -
提高代码质量，减少潜在 Bug：
CODE_QUALITY
等规则集能帮助我们发现并修复潜在的代码异味和不规范写法，例如未使用的变量、冗余的代码块等，从而提高代码的健壮性和可维护性。 -
开箱即用，快速上手： 对于不熟悉 Rector 配置的开发者来说，
eliashaeussler/rector-config
提供了一个极佳的起点。它已经为你打包了许多常用且经过验证的规则，你只需根据自己的项目需求进行少量调整即可。 -
易于维护和扩展： 即使是个人项目，随着时间推移，维护一个复杂的
rector.php
也会变得麻烦。而这种封装的配置方式，让未来的调整和扩展变得更加简单明了。
总结
eliashaeussler/rector-config并非一个革命性的新工具，但它巧妙地利用了 Composer 的依赖管理和 PHP 的面向对象特性，将 Rector 的配置过程变得异常简洁高效。对于那些希望自动化 PHP 项目升级、统一代码规范、提升开发效率的开发者来说，它无疑是一个值得尝试的宝藏。虽然它被定义为作者的“个人配置”，但其提供的通用性和便捷性，足以让它成为你日常开发中的得力助手。告别繁琐的手动调整，让 Rector 和
eliashaeussler/rector-config助你轻松驾驭 PHP 项目的演进！
