PHP ReflectionAttribute 怎么读取重复属性：getAttributes、实例化与参数校验

项目里用 PHP Attribute 标记路由、权限或缓存策略时，真正容易混淆的地方不是写出 #[Route('/orders')]，而是读取阶段到底拿到了什么。getAttributes() 返回的是描述属性的 ReflectionAttribute 数组；只有调用 newInstance()，PHP 才会真正创建属性对象并执行构造参数校验。

一个实用判断：反射扫描阶段先读取名称和原始参数，确认目标属性后再实例化；这样未知属性或参数错误不会在无关代码上过早触发。

PHP 8 Attributes 先经过描述层

假设控制器方法上挂了两个访问规则。这里让 Attribute 支持重复使用，因为同一个方法可能同时接受两种角色：

读取方法时先拿到两个描述对象。它们能告诉你属性类名和传入参数，但这一步还没有调用 AllowRole 的构造函数。

用 getAttributes() 区分全部属性和指定属性

ReflectionMethod::getAttributes() 不传名称时会返回方法上的全部属性。传入类名后则只保留这个名字对应的属性：

$method = new ReflectionMethod(OrderController::class, 'export');

$all = $method->getAttributes();
$roles = $method->getAttributes(AllowRole::class);

foreach ($roles as $attribute) {
    var_dump($attribute->getName());
    var_dump($attribute->getArguments());
}
// AllowRole
// ['editor']
// AllowRole
// ['auditor']

返回数组的顺序与声明顺序一致，业务代码可以据此保留多个规则。若只需要识别某个接口的实现类，可以使用 ReflectionAttribute::IS_INSTANCEOF，它的语义不是“模糊字符串匹配”，而是按类关系筛选。

重复属性必须在声明阶段打开开关

没有 IS_REPEATABLE 时，同一个 Attribute 在一处声明两次会触发编译阶段错误。不要等到反射循环里再处理这个问题，因为程序根本不会走到 getAttributes()。

另一个常见误区是只看 getName() 是否相等，却忘记属性可能带命名空间。生产代码中更稳妥的方式是使用完整类名常量，例如 AllowRole::class，不要手写短字符串。

什么时候该调用 newInstance()

getArguments() 返回的是声明时记录的参数，适合做日志、索引或快速过滤。真正需要读取属性对象的公开字段和方法时，再调用 newInstance()：

$allowedRoles = [];
foreach ($roles as $reflectionAttribute) {
    $role = $reflectionAttribute->newInstance();
    $allowedRoles[] = $role->role;
}

if (!in_array($currentUserRole, $allowedRoles, true)) {
    throw new RuntimeException('forbidden');
}

实例化的边界很明确：Attribute 类不存在、构造器参数不符合声明，或者构造器主动抛出异常，错误会在 newInstance() 这里暴露。反射扫描器可以先收集 getName() 和 getArguments()，把未知属性交给兼容层处理，确认支持后再实例化。

用接口筛选一组可扩展属性

当权限属性不止一个类时，可以定义一个接口作为反射筛选入口。精确匹配只会找到指定类；加上 IS_INSTANCEOF 后，满足接口关系的 Attribute 也会被选中：

interface Policy {}

#[Attribute(Attribute::TARGET_METHOD)]
final class AllowRole implements Policy
{
    public function __construct(public string $role) {}
}

$policies = $method->getAttributes(Policy::class, ReflectionAttribute::IS_INSTANCEOF);
foreach ($policies as $policy) {
    $instance = $policy->newInstance();
    // 进入统一的 Policy 处理流程
}

这个写法给扩展留下空间，但也意味着所有实现类的构造约定需要在团队内固定下来。接口只保证类型关系，不会替你保证每个属性都有同样的参数名或业务含义。

常见问题

getAttributes() 会直接执行 Attribute 构造器吗？

不会。它先返回 ReflectionAttribute 描述对象；调用 newInstance() 后才会创建对应属性实例并进行构造参数校验。

isRepeated() 和 IS_REPEATABLE 是一回事吗？

不是。IS_REPEATABLE 是声明 Attribute 时允许重复使用的标志；ReflectionAttribute::isRepeated() 用于查看当前反射结果是否属于重复声明。

为什么 getAttributes('Policy') 返回空数组？

默认是精确类名筛选。如果目标属性实现了 Policy 接口，应同时传入 ReflectionAttribute::IS_INSTANCEOF。

未知 Attribute 能否先读取参数？

可以先读取名称和参数描述，但不要调用它的 newInstance()；如果对应类不存在，实例化时会抛出错误。

把反射读取写成可验收的小流程

上线前可以按四步检查：先确认 Attribute 的目标范围和是否允许重复；再用类名常量筛选；接着用 getArguments() 记录或预检；最后只对确认支持的结果调用 newInstance()。测试里同时覆盖单个属性、重复属性、接口筛选和错误构造参数，反射层的行为就不会只停留在“能读到名称”。