PHP ReflectionAttribute 怎样读取注解声明的目标与参数

PHP 8 的 Attribute 写在声明旁边，但反射 API 先返回的是描述对象，不是已经构造好的属性实例。读取注解时，通常先对 ReflectionClass、ReflectionMethod 或 ReflectionParameter 调用 getAttributes()，再用 ReflectionAttribute 读取名称、参数、目标位掩码和重复状态；只有确实需要业务对象时，才调用 newInstance()。

这个顺序适合做路由扫描、参数校验和配置索引：先用元数据筛选，避免因为参数错误或属性类缺失过早实例化。

先把 ReflectionAttribute 的四类信息分开

同一个 ReflectionAttribute 可以看成“声明记录”。getName() 给出属性类名，getArguments() 给出声明时传入的值，getTarget() 表示它附着在哪类声明上，isRepeated() 则说明同名属性是否在同一元素上重复出现。它们都不会返回属性类实例。

先声明一个可重复的 Route 属性

下面的属性允许放在类、方法和参数上，并允许同一位置出现多次。构造函数使用命名参数时，反射结果会保留参数名，后续代码更容易按字段读取。

从类、方法和参数读取同一套信息

读取入口取决于属性贴在哪个声明上。传入 Route::class 可以只取目标属性；不传名称则会拿到该反射对象上的全部属性。下面的函数把三类反射对象统一为一条输出记录，并刻意在实例化前读取元数据。

getAttributes(Route::class) as $attribute) {
        $rows[] = [
            'name' => $attribute->getName(),
            'arguments' => $attribute->getArguments(),
            'target' => $attribute->getTarget(),
            'repeated' => $attribute->isRepeated(),
        ];
    }

    return $rows;
}

// 三个入口分别对应类、方法和参数声明。
$class = new ReflectionClass(OrderController::class);
$method = $class->getMethod('show');
$parameter = $method->getParameters()[0];

$classRoutes = readRoutes($class);
$methodRoutes = readRoutes($method);
$parameterRoutes = readRoutes($parameter);

// 需要业务对象时再实例化，避免把筛选阶段和构造阶段混在一起。
$route = $method->getAttributes(Route::class)[0]->newInstance();

这里的 arguments 可能是 [0 => '/orders']，也可能是 ['path' => '/orders', 'method' => 'GET']。因此消费端不要只读取数字下标；如果团队允许两种写法，先统一成自己的配置结构，再交给业务层。

getTarget 是位掩码，迁移时使用常量

getTarget() 返回的是 Attribute::TARGET_* 位掩码，不应把返回值直接写成 1、4、32。属性贴在方法上时可以与 Attribute::TARGET_METHOD 做按位与；这样即使常量值在版本间变化，代码仍然表达正确含义。

 '类',
        Attribute::TARGET_METHOD => '方法',
        Attribute::TARGET_PARAMETER => '参数',
        Attribute::TARGET_PROPERTY => '属性',
        Attribute::TARGET_FUNCTION => '函数',
    ];

    // PHP 8.5 增加了类常量目标，旧版本没有这个常量。
    if (defined('Attribute::TARGET_CONSTANT')) {
        $names[constant('Attribute::TARGET_CONSTANT')] = '类常量';
    }

    foreach ($names as $flag => $label) {
        // 位掩码命中时返回语义标签，而不是裸数字。
        if (($target & $flag) === $flag) {
            return $label;
        }
    }

    return '未识别目标';
}

迁移旧扫描器时，重点检查两件事：是否仍把 getTarget() 当成单一固定数字；是否把所有属性都强制调用 newInstance()。PHP 8.5 的 Attribute::TARGET_CONSTANT 会让“类、方法、属性、参数”之外再多一个合法目标，目标映射应保留扩展空间。

落地前的回归检查清单

• 扫描类、方法、参数时使用各自的反射对象，不要期待类级属性自动出现在方法级结果中。
• 命名参数与位置参数都要覆盖；读取 getArguments() 后再做字段归一化。
• 允许重复属性时保留全部记录，并用 isRepeated() 标记，而不是覆盖同名键。
• 只有需要属性对象时才调用 newInstance()，并把构造异常作为配置错误处理。
• 目标判断使用 Attribute::TARGET_* 常量，PHP 8.5 之后补上类常量分支。

常见问题

getArguments() 返回的是构造后的属性对象吗？

不是。它返回声明时传入的参数数组；需要带类型属性和构造逻辑的对象时，再调用 newInstance()。

怎样只读取某一种 Attribute？

给 getAttributes() 传入属性类名，例如 getAttributes(Route::class)。需要匹配子类或接口时，再考虑 ReflectionAttribute::IS_INSTANCEOF 标志。

isRepeated() 为 false 就代表属性只能出现一次吗？

它表示当前同名属性在这个代码元素上是否被重复使用；能否重复声明仍由属性类声明时的 Attribute::IS_REPEATABLE 决定。

官方资料：https://www.php.net/manual/en/language.attributes.reflection.php、https://www.php.net/manual/en/class.reflectionattribute.php。