Psalm 的 psalm-refactor 重构工具详解:批量移动与重命名类、方法、命名空间
Psalm 的 psalm-refactor 重构工具详解:批量移动与重命名类、方法、命名空间
Psalm 除了静态分析定位问题,还内置了一个专门用于结构性变更的重构工具 psalm-refactor,支持在移动或重命名类、方法的同时自动更新代码库中所有可识别的引用。本文基于仓库中的官方文档 refactoring.md 展开,逐条讲清五种重构场景的命令用法,并结合 Refactor.php 与 ProjectAnalyzer.php 的源码,说明其参数解析、通配符展开、引用改写与文件迁移的完整机制。
工具的两种调用入口
Psalm 的重构功能可以独立使用,也可以挂载在 psalm 主命令之后。文档给出的两种等价入口为:
vendor/bin/psalm-refactor [options]
vendor/bin/psalm --refactor [options]
独立入口对应的可执行脚本 psalm-refactor 本身只有 9 行,它引入并调用了 Psalm\Internal\Cli\Refactor 类的 run 方法:
// psalm-refactor
require_once __DIR__ . '/src/Psalm/Internal/Cli/Refactor.php';
Refactor::run($argv);
即 src/Psalm/Internal/Cli/Refactor.php 中的 Refactor::run() 是两类入口共同的实际执行体。从源码结构看,Refactor::run() 与 psalm、psalter 共享同一套基础设施:Xdebug 检测、自动加载器注册、CliUtils::initializeConfig() 读取 psalm.xml 配置、ProjectAnalyzer 驱动完整扫描,只是最后把扫描结果导向重构而非报错。
命令行参数速查
Refactor::run() 中定义了合法参数白名单(见 Refactor.php 第 79-83 行):
| 参数 | 说明 |
|---|---|
-h, --help |
显示帮助信息 |
--move "[Identifier]" |
指定要移动/迁移的符号(类、方法、属性、常量),可与 --into 连用 |
--into "[Destination]" |
指定 --move 的目标类或命名空间 |
--rename "[Identifier]" |
指定要重命名的符号 |
--to "[NewIdentifier]" |
指定 --rename 的新标识符 |
-c, --config=psalm.xml |
指定 psalm.xml 配置文件路径 |
-r, --root=<path> |
以全局方式运行 Psalm 时必须提供的项目根目录 |
--threads=<n>, --scan-threads=<n> |
多线程加速分析 |
--debug, --debug-by-line, --debug-emitted-issues |
调试信息 |
--no-progress |
关闭进度指示 |
-f, -m |
分别控制输出格式与颜色(短选项白名单中的 f:、m) |
帮助文本(Refactor.php 第 132-167 行)还揭示了一个文档未强调的能力:一次可以移动多个项目,用逗号分隔传入即可,例如:
--move "Ns\Foo::bar,Ns\Foo::baz" --into "Biz\Bang\DestinationClass"
参数解析采用了一个小的状态机:--move / --rename 分别把 operation 置为 move / rename,遇到 --into / --to 时要求前面必须已有待移动/重命名的符号,否则报错退出(Refactor.php 第 218-294 行)。所有映射最终汇总进 $to_refactor 数组(源 => 目标 的形式),若为空则提示 No --move or --rename arguments supplied 并退出。
--into 的处理有一个值得注意的细节:当被移动的是方法(含 ::)时,目标只替换类部分,方法名保持不变($arg . '::' . $identifier_name);当被移动的是类时,目标命名空间与原类名拼接($arg . '\\' . $class_name)。这正是"移动到某命名空间"与"重命名"两个语义在参数层的落地方式。
场景一:把一个命名空间下的所有类迁移到另一个命名空间
vendor/bin/psalm-refactor --move "Ns1\*" --into "Some\Other\Namespace"
此命令把 Ns1 下的所有类(如 Ns1\Foo、Ns1\Baz)移入目标命名空间,文件会按需移动(Files are moved as necessary)。
通配符的展开并不发生在 CLI 层,而是在分析阶段由 ProjectAnalyzer::interpretRefactors() 完成(ProjectAnalyzer.php 第 507-523 行):当 source 与 destination 都以 * 结尾时,遍历 codebase->classlike_storage_provider->getAll() 中所有已知的类,凡是名字以 Ns1\ 为前缀的类,都会生成一条 Ns1\Foo => Some\Other\Namespace\Foo 的具体映射,替换掉原始的通配条目。这解释了为什么文档示例中源侧必须写 Ns1\*——它依赖的是扫描阶段收集到的全量类列表,而不是简单的字符串替换。
场景二:在命名空间之间移动单个类
vendor/bin/psalm-refactor --move "Ns1\Foo" --into "Ns2"
把类 Ns1\Foo 移入命名空间 Ns2,代码库中所有对 Ns1\Foo 的引用都会被改写为 Ns2\Foo,文件同样按需移动。
对"纯类到纯类"(source 与 destination 都不含 ::)的映射,interpretRefactors() 的处理(ProjectAnalyzer.php 第 535-564 行)包括:
- 校验源类存在:
classlikes->hasFullyQualifiedClassName($source),否则抛出RefactorException('Source class ... doesn't exist'); - 校验目标类不存在:目标已存在时抛
Destination class ... already exists,避免命名冲突; - 将
source => destination记入codebase->classes_to_move,并为目标创建一个占位的ClassLikeStorage(继承源的location、stmt_location、aliases,把aliases的namespace更新为目标命名空间); - 记入
codebase->class_transforms,供后续改写文件内容与引用时使用。
场景三:移动并重命名一个类
vendor/bin/psalm-refactor --rename "Ns1\Foo" --to "Ns2\Bar\Baz"
把类 Ns1\Foo 移入命名空间 Ns2\Bar 并重命名为 Baz,所有 Ns1\Foo 引用变为 Ns2\Bar\Baz,文件按需移动。
从源码结构看,--rename --to 走的是与场景二相同的"类到类"分支(interpretRefactors() 并不区分该映射来自 --move 还是 --rename,只按 源 => 目标 对处理),因此校验逻辑与 classes_to_move / class_transforms 的登记方式完全一致。
场景四:在类之间移动方法
vendor/bin/psalm-refactor --move "Ns1\Foo::bar" --into "Ns2\Baz"
把 Ns1\Foo 中名为 bar 的方法移入 Ns2\Baz,所有对 Ns1\Foo::bar 的调用改为 Ns2\Baz::bar。
文档明确指出其约束:静态方法可以在任意类之间移动;实例方法只能移入该类的子类。这条约束在源码中有精确对应(ProjectAnalyzer.php 第 591-613 行):
if (!$source_method_storage->is_static
&& !isset(
$destination_class_storage->parent_classes[strtolower($source_method_id->fq_class_name)],
)
) {
throw new RefactorException(
'Cannot move non-static method ' . $source
. ' into unrelated class ' . $destination_parts[0],
);
}
即:源与目标类不同时,若方法是实例方法且源类不在目标类的 parent_classes 集合中,直接抛出 RefactorException。此外方法移动还有两道前置校验:
- 目标方法已存在时报
Destination method ... already exists; - 目标类不存在时报
Destination class ... doesn't exist。
通过校验后,映射分别落入 codebase->methods_to_move(跨类移动)或 codebase->methods_to_rename(同类的纯重命名),并登记一条调用点正则变换(ProjectAnalyzer.php 第 612 行):
$this->codebase->call_transforms[$source_lc . '\((.*\))'] = $destination . '($1)';
这条规则把 Ns1\Foo::bar(...) 形式的调用整体改写为 Ns2\Baz::bar(...),参数部分通过捕获组 (.*) 原样保留——这就是"自动更新所有引用"的实现路径之一。
场景五:移动并重命名一个方法
vendor/bin/psalm-refactor --rename "Ns1\Foo::bar" --to "Ns2\Baz::bat"
把方法 Ns1\Foo::bar 移入 Ns2\Baz 并重命名为 bat,所有 Ns1\Foo::bar 调用变为 Ns2\Baz::bat。
与场景四类似,--rename --to 在方法场景下直接以完整的 目标类::新名 作为映射值($to_refactor<a href="https://link.gitcode.com/i/eb86b47cdead3aaf89bba15927778005" target="_blank">$last_arg] = $arg,见 [Refactor.php 第 278 行),interpretRefactors() 会据此区分"跨类移动"(methods_to_move)与"同类改名"(methods_to_rename),并同样登记 call_transforms 规则。
文档之外的扩展能力:属性、常量与批量移动
阅读 interpretRefactors() 的完整实现(ProjectAnalyzer.php 第 501-700 行)可以发现,除了类与方法,该状态机还支持两类符号的重构,文档未单独列出,但命令格式与方法完全一致:
- 属性:形如
Ns1\Foo::$bar的标识符(源标识符含$)。限制是:跨类移动只允许静态属性,非静态属性会抛Cannot move non-static property(第 641-655 行);映射记入properties_to_move/properties_to_rename与property_transforms。 - 类常量:
Ns1\Foo::CONSTANT形式。会校验源常量存在(getConstantsForClass)、目标类存在、目标常量不冲突,记入class_constants_to_move/class_constants_to_rename与class_constant_transforms(第 661-694 行)。
对于无法识别的源符号,最终抛出 RefactorException('Psalm cannot locate ' . $source),保证错误在使用前尽早暴露。
底层工作流程:从命令到代码迁移
把源码串起来看,一次 psalm-refactor 执行的完整链路是:
- CLI 解析:
Refactor::run()解析参数、构建$to_refactor映射表(Refactor.php 第 213-299 行); - 登记重构:
ProjectAnalyzer::refactorCodeAfterCompletion($to_refactor)把映射存入$this->to_refactor并置codebase->alter_code = true(ProjectAnalyzer.php 第 1076-1081 行),此时尚未做任何解释; - 全量扫描:
$project_analyzer->check($current_dir)正常扫描整个项目,收集类、方法、属性、常量的存储与所有引用; - 解释重构:
interpretRefactors()在此之后运行,展开通配符、做存在性与冲突校验,把映射分类落入classes_to_move、methods_to_move、properties_to_move、class_constants_to_move以及各*_transforms表(ProjectAnalyzer.php 第 501-700 行); - 执行迁移:
prepareMigration()调用codebase->classlikes->moveMethods()、moveProperties()、moveClassConstants()等,完成声明位置的移动,配合class_transforms/call_transforms改写全部引用,文件随声明体一起移动到目标目录结构。
仓库中有一组对应的测试用例验证了上述能力,可作为行为佐证:ClassMoveTest.php(类移动)、NamespaceMoveTest.php(命名空间迁移)、MethodMoveTest.php(方法移动),它们位于 tests/FileManipulation/ 目录下。
与 psalter(代码修复工具)的分工
Psalm 还有另一个修改代码的工具 Psalter(psalter / psalm --alter),它面向的是基于问题名的自动修复(补全返回类型、参数类型、删除未使用变量等),详见 fixing.md;而 psalm-refactor 面向的是结构性重构——类、方法、属性、常量的移动与重命名,且以 --move/--into 与 --rename/--to 两种显式操作驱动。两者共享 alter_code 模式下的代码改写基础设施(例如 FileManipulation.php 定义的 start/end/insertion_text 文本变换模型),但触发方式和适用场景不同:想批量补类型用 psalter,想动类与方法结构则用 psalm-refactor。
使用建议与限制
- 重构依赖 Psalm 对代码库的完整索引,请确保项目已配置好
psalm.xml(可用-c指定),且所有被移动符号及其引用都在扫描范围内,否则引用可能漏改; - 移动操作会真实移动文件,建议在版本控制下执行并在运行后
git diff复核;目标类/方法/属性/常量重名时会直接以RefactorException失败,不会产生半成品的改动; - 实例方法只能移入子类、跨类属性移动仅限静态属性,这是当前实现的硬性边界,规划重构时应提前考虑;
- 出现意外时可用
--debug、--debug-by-line、--debug-emitted-issues排查分析过程中的中间状态。