如何用Rector将nelmio/api-doc-bundle的PHP注解转为属性

针对nelmio/open-api-bundle的注解转属性需求，除手动修改外，以下几种自动化方案可行：

1. 自定义Rector规则 #

Rector的预定义集合不覆盖nelmio注解，但可以自行编写规则实现转换：

• 创建自定义Rector规则类，继承AbstractRector，指定处理ClassMethod节点（API端点注解通常标注在控制器方法上）
• 在refactor方法中识别目标注解（如@OA\Get、@OA\Response），将其转换为对应的属性节点，完整保留原注解的所有参数
• 在rector.php中注册该规则，运行rector process执行批量转换

简化的规则示例：

use Rector\Core\Rector\AbstractRector;
use PhpParser\Node;
use PhpParser\Node\Stmt\ClassMethod;
use PhpParser\Node\Attribute;
use PhpParser\Node\Name;

class NelmioAnnotationToAttributeRector extends AbstractRector
{
    public function getNodeTypes(): array
    {
        return [ClassMethod::class];
    }

    public function refactor(Node $node): ?Node
    {
        /** @var ClassMethod $classMethod */
        $classMethod = $node;

        foreach ($classMethod->attrGroups as $attrGroup) {
            foreach ($attrGroup->attrs as $annotation) {
                // 匹配所有OA命名空间下的注解
                if (str_starts_with($this->getName($annotation->name), 'OA\\')) {
                    $attributeName = new Name($this->getName($annotation->name));
                    $attribute = new Attribute($attributeName, $annotation->args);
                    $annotation->replaceWith($attribute);
                }
            }
        }

        return $classMethod;
    }
}

注册规则到rector.php：

use YourNamespace\NelmioAnnotationToAttributeRector;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();
    $services->set(NelmioAnnotationToAttributeRector::class);
};

2. 自定义PHP-CS-Fixer规则 #

PHP-CS-Fixer支持自定义修复规则，适合处理语法层面的注解转属性：

• 实现FixerInterface，遍历AST节点识别以/** @OA\开头的注释
• 将/** @OA\XXX(...) */格式的注释转换为#[OA\XXX(...)]属性语法
• 配置规则后运行php-cs-fixer fix完成批量替换

3. 正则批量替换（适合简单场景） #

如果项目中nelmio注解格式统一，可借助正则做快速替换：

• 针对常见注解编写正则表达式，比如将/\*\* @OA\Get\(path="([^"]+)", summary="([^"]+)"\) \*/替换为#[OA\Get(path="$1", summary="$2")]
• 使用IDE的全局替换功能（如PHPStorm的「路径中替换」）或命令行工具（sed）执行替换
• 注意：此方法仅适用于结构简单的注解，嵌套参数（如多层@OA\Response）容易出错，替换后需逐一校验

4. PHPStan自定义规则辅助修复 #

编写PHPStan规则识别nelmio注解，生成自动修复建议：

• 实现PHPStan的Rule接口，检测代码中的nelmio注解节点
• 生成对应的属性替换修复提示，开启自动修复后可批量应用

内容的提问来源于stack exchange，提问作者Diplodoco