RectorPHP 升级 Symfony 项目时遇到的类未找到问题解析

问题背景

在使用 RectorPHP 工具升级 Symfony 项目版本时，开发者经常会遇到类未找到的错误。特别是在从 Symfony 5.2 升级到 7.2 的过程中，系统提示 Class "Rector\Symfony\Set\SymfonyLevelSetList" not found 错误。

错误原因分析

这个问题的根本原因是 RectorPHP 在版本演进过程中对 API 进行了调整。具体来说：

1. SymfonyLevelSetList 类在 Rector 0.19.2 版本后已被弃用
2. 新版本中采用了更细粒度的集合列表方式
3. 需要逐个版本迭代升级，而不是一次性升级到目标版本

解决方案

正确的配置方式应该是：

1. 使用 SymfonySetList 替代已弃用的 SymfonyLevelSetList
2. 采用分步升级策略，例如先升级到 6.2，再到 7.2
3. 确保已正确安装 rector-symfony 扩展包

最佳实践配置示例

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\SetList;
use Rector\Set\ValueObject\LevelSetList;
use Rector\Symfony\Set\SymfonySetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/src',
    ]);

    $rectorConfig->skip([
        __DIR__ . '/vendor',
    ]);

    $rectorConfig->disableParallel();

    $rectorConfig->sets([
        LevelSetList::UP_TO_PHP_84,
        SymfonySetList::SYMFONY_62,
        SymfonySetList::SYMFONY_63,
        // 逐步添加更高版本
        SetList::CODING_STYLE,
        SetList::CODE_QUALITY,
        SymfonySetList::SYMFONY_CODE_QUALITY,
        SymfonySetList::SYMFONY_CONSTRUCTOR_INJECTION,
    ]);
};

升级策略建议

1. 分步升级：不要直接从 5.2 跳到 7.2，应该逐步升级
2. 版本测试：每次升级一个次要版本后，充分测试系统功能
3. 依赖检查：确保项目依赖与目标 Symfony 版本兼容
4. 容器配置：考虑添加容器配置以获取更好的重构效果

常见误区

1. 试图一次性升级到最新版本
2. 忽略中间版本的破坏性变更
3. 未正确排除 vendor 目录导致性能问题
4. 未阅读最新文档而使用已弃用的类和方法

通过遵循这些指导原则，开发者可以更顺利地进行 Symfony 项目的版本升级，避免常见的配置错误和升级陷阱。