PHP ReflectionClass 怎样读取类级 Attribute

PHP 8 以后，类级 Attribute 不需要靠注释解析。先把目标类交给 ReflectionClass，再调用 getAttributes()，就能得到一组 ReflectionAttribute 对象；需要读取参数时调用 getArguments()，需要真正创建 Attribute 对象时再调用 newInstance()。

官方地址：https://www.php.net/manual/en/reflectionclass.getattributes.php

本文只讨论类级 Attribute：包括读取、按名称过滤、按接口或父类匹配，以及实例化参数。字段、方法和类常量的 Attribute 要从对应的 Reflection 成员读取。

先用 ReflectionClass 取得类级 Attribute

先声明一个只能放在类上的 Attribute，再把它标记到业务类。ReflectionClass::getAttributes() 不传参数时，会返回目标类直接声明的全部类级 Attribute。

getAttributes();

// 先读取元数据名称，只有需要参数时才继续实例化。
foreach ($attributes as $attribute) {
    echo $attribute->getName(), PHP_EOL;
}
// 输出：ResourceTag

这里得到的元素是 ReflectionAttribute，不是 ResourceTag 实例。这样做的好处是可以先查看名称和参数，避免在 Attribute 类不存在、参数不符合构造函数时过早创建对象。

按 Attribute 类名过滤结果

当一个类挂了多个 Attribute 时，可以把 Attribute 类名传给 getAttributes()。默认的第二个参数是 0，表示只匹配同名类；如果要把实现某个接口或继承某个父 Attribute 的类型一起找出来，可以使用 ReflectionAttribute::IS_INSTANCEOF。

getAttributes(ShortCache::class);

// 接口匹配：把实现 CachePolicy 的 Attribute 一起取出。
$policies = $reflection->getAttributes(
    CachePolicy::class,
    ReflectionAttribute::IS_INSTANCEOF
);

echo count($exact), PHP_EOL;    // 输出：1
echo count($policies), PHP_EOL; // 输出：2

过滤名称只影响结果集合，不会把结果自动变成构造后的对象。第二个参数只有在传入名称时才有意义；不传名称时，通常直接取得全部类级 Attribute 更清楚。

读取参数并在需要时实例化

反射阶段可以先用 getArguments() 查看构造参数。确定类型和参数都可信后，再用 newInstance() 创建真正的 Attribute 对象。

getAttributes(RouteGroup::class)[0] ?? null;

if ($route !== null) {
    // 先查看原始参数，便于在实例化前做缺失值和类型判断。
    $arguments = $route->getArguments();
    echo $arguments[0], PHP_EOL;

    // 构造函数参数确定后，才创建 RouteGroup 实例。
    $group = $route->newInstance();
    echo implode(',', $group->methods), PHP_EOL;
}

newInstance() 会按照 Attribute 类的构造函数重新解释参数。它适合把元数据交给路由、缓存或权限注册器，但不要为了打印名称而无条件实例化全部结果。

继承与成员范围有哪些边界

最容易误判的是“类级 Attribute 会不会随继承自动出现”。PHP 官方反射说明中，类级 Attribute 不会因为反射子类而自动继承；反射子类时，getAttributes() 主要返回子类自己声明的类级 Attribute。父类、接口和 Trait 上的声明不能直接当成子类的类级结果。

另一个边界是反射对象的范围：ReflectionClass 读取类声明，ReflectionProperty 读取属性声明，ReflectionMethod 读取方法声明。如果把字段 Attribute 贴到属性上，却在 ReflectionClass 上查找，结果为空并不代表 Attribute 没有生效，而是查错了反射对象。

因此，排查“读取不到”时按三步看：目标类是否真的声明了 Attribute；Attribute 的目标范围是否允许 TARGET_CLASS；代码是否使用了和声明位置对应的 Reflection 对象。

常见问题

为什么 getAttributes 返回的是 ReflectionAttribute？

这是反射层的描述对象。先读名称和参数，再决定是否调用 newInstance()，可以把类缺失、参数错误等问题留在真正消费元数据的地方处理。

什么时候要传 ReflectionAttribute::IS_INSTANCEOF？

当你按接口或父 Attribute 归类筛选，并希望同时得到其实现类或子类时使用。只想得到指定 Attribute 类本身时，省略第二个参数即可。

子类为什么读不到父类的类级 Attribute？

类级 Attribute 不会自动继承。若业务确实需要沿父类查找，要在应用层明确遍历父类并规定覆盖顺序，不要把反射结果误认为 PHP 已经替你合并。

简单记忆就是：ReflectionClass 找类，getAttributes() 取描述，getArguments() 看参数，newInstance() 才创建对象；过滤时再根据需求选择精确类名或 IS_INSTANCEOF。