PHP 反射怎么读取类属性并筛选自定义 Attribute

PHP 反射筛选自定义 Attribute，核心不是遍历对象值，而是先用 ReflectionClass::getProperties() 拿到类属性，再在每个 ReflectionProperty 上调用 getAttributes(ColumnLabel::class)。这样返回的只会是目标标记，随后用 getArguments() 读取声明参数，或用 newInstance() 得到类型明确的 Attribute 对象。

先把自定义 Attribute 的目标锁在属性上

以字段映射为例，先声明一个只允许放在属性上的 ColumnLabel。构造函数保存数据库列名，类型声明让后续调用方少做字符串猜测：

debugNote 没有标记，后面的筛选结果应当忽略它。TARGET_PROPERTY 也不会自动让 Attribute 出现在反射结果里，它只是约束声明位置。

ReflectionClass 如何找到带 Attribute 的类属性

ReflectionClass 描述类本身，ReflectionProperty 描述其中一个属性。遍历时先保留属性名、类型和标记结果，方便把“没有标记”和“标记参数为空”区分开：

function describeColumns(string $className): array
{
    $reflection = new ReflectionClass($className);
    $columns = [];

    foreach ($reflection->getProperties() as $property) {
        // 传入类名后，只筛选 ColumnLabel，不必手动比较名称。
        $attributes = $property->getAttributes(ColumnLabel::class);
        if ($attributes === []) {
            continue;
        }

        $attribute = $attributes[0];
        $columns[] = [
            'property' => $property->getName(),
            'type' => (string) $property->getType(),
            'column' => $attribute->getArguments()['name'],
        ];
    }

    return $columns;
}

这里的 getAttributes() 返回的是 ReflectionAttribute 数组，不是 ColumnLabel 数组。属性名和声明类型来自 ReflectionProperty，标记参数来自反射属性对象，两条信息不要混在一起。

用 getAttributes 精确筛选并读取 Attribute 参数

最常用的写法是传入 ColumnLabel::class。不传名称则会拿到该属性上的全部标记，适合做通用扫描；传入名称则只保留同名 Attribute。若多个同类标记并存，应先明确是否允许重复，再决定取第一个还是遍历全部。

只想拿配置数组时使用 getArguments()；需要调用方法、依赖类型或让 PHP 校验构造参数时使用 newInstance()：

function readColumnLabel(ReflectionProperty $property): ?ColumnLabel
{
    // 先按类名筛选，避免把其他 Attribute 当成字段配置。
    $items = $property->getAttributes(ColumnLabel::class);
    if ($items === []) {
        return null;
    }

    // 实例化后可直接访问 readonly 属性，构造参数也会被检查。
    return $items[0]->newInstance();
}

继承、私有属性和缓存是最容易漏掉的边界

如果 Attribute 实现了某个接口，只有传入 ReflectionAttribute::IS_INSTANCEOF 才会按继承关系匹配；普通类名筛选不会自动扩大范围。getProperties() 可以返回私有属性的结构信息，但读取结构不等于读取实例值，业务层仍应遵守封装边界。

反射扫描通常发生在启动或构建元数据缓存阶段。可以按类名缓存最终的字段描述，避免每次请求重复创建 ReflectionClass。如果允许重复 Attribute，就不要默默取下标 0；应遍历全部结果，或者在定义 Attribute 时关闭重复使用并尽早暴露声明错误。

相关问答

为什么 getAttributes 返回的不是 ColumnLabel？

因为它先返回描述 Attribute 声明的 ReflectionAttribute，这样可以延迟读取参数或实例化。调用 newInstance() 后才得到 ColumnLabel 对象。

什么时候使用 IS_INSTANCEOF？

当筛选目标是接口或父类，希望拿到实现类标记时使用；只找某一个具体 Attribute 类时，传类名做精确匹配更容易控制结果。

私有属性能不能被扫描？

可以扫描其声明信息，包括名称、类型和 Attribute；但扫描结构与读取对象私有值是两回事，不要为了映射方便而绕过领域对象的访问约束。

发布前检查清单

• 自定义 Attribute 已使用 TARGET_PROPERTY，并明确是否允许重复。
• 筛选点在 ReflectionProperty 上，精确类名和 IS_INSTANCEOF 没有混用。
• 调用方根据需要选择 getArguments() 或 newInstance()，没有把反射描述对象误当成业务对象。
• 生产环境对最终字段描述做缓存，并为继承、私有属性和无标记属性准备了测试。