PHP ReflectionAttribute 按接口筛选 Attribute 的实现方式

需要把多个 PHP Attribute 交给同一个扫描器处理时，不必为每个具体类写一组筛选逻辑。更稳妥的做法是先定义一个公共接口，再把接口名传给 getAttributes()，同时指定 ReflectionAttribute::IS_INSTANCEOF。这样返回结果会包含实现该接口的 Attribute 类；如果省略这个 flag，默认只做精确类名匹配，接口通常得到空数组。

先把多个 Attribute 归入公共接口

接口不需要本身成为一个 Attribute，它只承担“分类契约”的作用。真正应用到类或属性上的，是实现该接口并带有 #[Attribute] 的具体类。下面用缓存和审计两个标签说明这种关系：

理解 getAttributes 的精确匹配与接口匹配

ReflectionClass::getAttributes()、ReflectionProperty::getAttributes() 等方法都有 $name 和 $flags 两个关键参数。传入 CacheTag::class 且保持默认 flag，结果只包含 CacheTag；传入 MetadataTag::class 后，必须追加 ReflectionAttribute::IS_INSTANCEOF，结果才会包含 CacheTag 和 AuditTag。

用 ReflectionClass 和 ReflectionProperty 完成筛选

筛选结果先保留为 ReflectionAttribute，这一步不会立即构造用户定义的 Attribute 对象。只有真正需要读取构造参数或执行后续逻辑时，才调用 newInstance()。将“发现”和“实例化”分开，排查缺失类或参数类型问题会更容易。

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

    $tags = [];
    foreach ($reflected as $attribute) {
        // 只有确认是目标标签后才实例化，避免无关元数据提前触发错误。
        $instance = $attribute->newInstance();
        $tags[] = [
            'name' => $attribute->getName(),
            'arguments' => $attribute->getArguments(),
            'object' => $instance,
        ];
    }

    return $tags;
}

$classTags = readMetadataTags(new ReflectionClass(ProfileService::class));
$propertyTags = readMetadataTags(
    new ReflectionProperty(ProfileService::class, 'name')
);

// 生产代码中可在这里按 name 或实例类型分派不同处理器。
var_dump(array_column($classTags, 'name'));
var_dump(array_column($propertyTags, 'name'));

类级扫描会得到 CacheTag 和 AuditTag，属性级扫描只会得到挂在 $name 上的 CacheTag。这也是为什么扫描器的输入应当是具体的反射对象，而不是把类级和属性级结果混成一份。

按检查清单处理常见边界

1. 结果为空：先确认第二个参数是否传了 ReflectionAttribute::IS_INSTANCEOF，再确认具体 Attribute 是否真的实现了接口。
2. 目标不匹配：检查 Attribute::TARGET_CLASS、TARGET_PROPERTY 等位掩码；类上的标签不会自动出现在属性反射对象中。
3. 接口名称错误：优先使用 MetadataTag::class，不要手写命名空间字符串，避免重构后筛选不到结果。
4. 过早实例化：先用 getName() 和 getArguments() 做识别，确认需要执行时再调用 newInstance()。

常见问题

为什么传接口名却没有返回 Attribute？

因为默认 $flags 是 0，只匹配精确类名。把接口名和 ReflectionAttribute::IS_INSTANCEOF 一起传入，才会按接口实现关系筛选。

ReflectionAttribute::IS_INSTANCEOF 只能匹配接口吗？

不能。它同时支持给定 Attribute 类的子类；PHP 手册将这种行为描述为基于 instanceof 的过滤。

getAttributes 会直接创建 Attribute 对象吗？

不会。它返回的是 ReflectionAttribute 描述对象，调用 newInstance() 后才会实例化并校验构造参数。