PHP attributes用 Reflection 读取自定义属性的实现方法

我第一次把 PHP attributes 接进一个小型路由扫描器时，最容易写错的不是 #[...] 语法，而是把“读到声明”误认为“已经得到属性对象”。更稳的顺序是：先建立 Reflection，调用 getAttributes()，用 getName() 或 getArguments() 检查元数据，确认需要执行构造逻辑后再调用 newInstance()。

官方文档：https://www.php.net/manual/en/language.attributes.reflection.php

先用 Reflection 拿到属性声明，再决定是否实例化

我更愿意把自定义属性当成写在代码旁边的配置，而不是注释。下面的例子给一个路由元数据，目标只放在方法上；这样扫描类时不会误把它当成类级配置。

getAttributes(RouteMeta::class);

foreach ($declared as $attribute) {
    // 先读取名字和构造参数；此时还没有创建 RouteMeta 对象。
    var_dump($attribute->getName(), $attribute->getArguments());
    $route = $attribute->newInstance();
    var_dump($route->path, $route->methods);
}

这里的关键是返回值类型。getAttributes() 给出一个 ReflectionAttribute 数组；getArguments() 适合做轻量检查或日志记录，newInstance() 才会按构造函数创建 RouteMeta。如果属性类不存在，或参数无法满足构造函数，错误会在实例化这一步暴露，因此扫描大量类时可以先收集名称，再决定是否实例化。

类、方法和属性的读取方式并不相同

Reflection 的入口要和属性实际挂载的位置对应。类级属性用 ReflectionClass，方法级属性用 ReflectionMethod，属性级元数据则用 ReflectionProperty。它们都提供 getAttributes()，但不会替你把其他层级一起递归扫描。

按名称筛选时，先使用属性类名通常更安全：$method->getAttributes(RouteMeta::class) 只关注这一种元数据。如果团队把属性设计成父类和子类，还可以使用 ReflectionAttribute::IS_INSTANCEOF 纳入子类；不传这个标志时，筛选更接近精确匹配。这个小差异会直接影响扫描结果，不能只靠数组数量判断配置是否存在。

getAttributes(
    RouteMeta::class,
    ReflectionAttribute::IS_INSTANCEOF
);

foreach ($attributes as $attribute) {
    // 实例化前仍可以先检查属性名称，保留更清晰的错误上下文。
    if ($attribute->getName() === RouteMeta::class) {
        $route = $attribute->newInstance();
        echo $route->path;
    }
}

重复属性和参数错误要在扫描器边界处理

如果一个属性允许重复挂载，需要在属性声明上增加 Attribute::IS_REPEATABLE，读取结果就可能有多个同名项。业务代码不要默认取下标 0，而要明确是合并、覆盖还是拒绝重复。相反，对于只允许一次的配置，发现多个结果时应尽早报出上下文。

我在实际接入时会把扫描过程拆成两层：第一层只读取名称、目标和参数，记录“哪个类的哪个方法声明了什么”；第二层才根据业务需要调用 newInstance()。这样构造函数校验失败时，日志里仍保留反射入口和属性名称，排查起来比直接抛出一条泛化错误更快。

相关问题

getAttributes() 返回的是自定义属性对象吗？

不是。它返回 ReflectionAttribute 描述对象；只有调用 newInstance() 后，才得到自定义属性类的实例。

为什么指定属性类后仍然读不到子类？

默认筛选偏向精确匹配。需要把继承层级纳入结果时，传入 ReflectionAttribute::IS_INSTANCEOF。

ReflectionClass 会自动读方法上的 attributes 吗？

不会。先从类反射对象拿到方法，再为每个方法建立 ReflectionMethod，最后调用方法级 getAttributes()。

把“声明读取”和“对象实例化”分开，PHP attributes 的使用就会清楚很多：简单扫描只读描述信息，真正需要业务配置时再创建实例；再配合正确的 Reflection 入口和筛选标志，后续扩展多个属性类型也不容易失控。