PHP ReflectionProperty::isVirtual 怎么识别属性钩子：可见性、默认值与反射兼容

把 PHP 对象交给序列化器、表单映射器或文档生成器之前，常见做法是用 ReflectionClass::getProperties() 遍历属性。PHP 8.4 引入属性钩子后，这个遍历多了一个容易漏掉的判断：属性可能只有计算逻辑，并没有可以读写的底层存储。此时，ReflectionProperty::isVirtual() 就是区分两类属性的直接入口。

为什么反射遍历不能再把每个属性都当成字段

在 PHP 8.3 及更早版本里，反射到的属性通常可以对应到对象里的一个存储字段。PHP 8.4 的 property hooks 允许把读取和写入逻辑贴在属性声明上，下面这个 label 只负责计算展示值：

class Product
{
    public string $name;

    public string $label {
        get => '商品：' . $this->name;
    }
}

name 有真实值，label 的值每次读取时计算。如果一个导出器把两者都当作可以直接持久化的字段，就可能重复保存展示值，或者在反序列化时错误地尝试给只读计算属性赋值。先判断 virtual，再决定是否进入字段读写流程，边界会清楚很多。

ReflectionProperty::isVirtual 的最小用法

方法不接收参数，返回布尔值。拿到具体属性后直接调用即可：

$reflection = new ReflectionClass(Product::class);

foreach ($reflection->getProperties() as $property) {
    printf(
        "%s: virtual=%s\n",
        $property->getName(),
        $property->isVirtual() ? 'yes' : 'no'
    );
}

对上面的类，预期结果是 name: virtual=no、label: virtual=yes。这里的判断只回答“这个属性是否为虚拟属性”，不会替你决定它是否公开、是否敏感或是否应该进入 API 响应。

三个声明形态，结果为什么不同

可以用一个类一次性验收这三种情况：

class Account
{
    public string $id;

    public string $displayId {
        get => 'ID-' . $this->id;
    }

    public string $email {
        set {
            $this->email = strtolower(trim($value));
        }
    }
}

$class = new ReflectionClass(Account::class);
foreach (['id', 'displayId', 'email'] as $name) {
    $property = $class->getProperty($name);
    var_dump($name, $property->isVirtual());
}

预期是 id=false、displayId=true、email=false。email 的 setter 虽然做了加工，但它仍把值写回名为 email 的属性，所以不是无存储的虚拟属性。

和 getHooks 一起使用时，先看能力再看实现

如果工具还需要知道属性有没有 get 或 set hook，可以在 PHP 8.4 中继续调用 getHooks()。它返回以 hook 名称为键的反射方法数组，没有 hook 时是空数组，返回顺序不应当作为逻辑依据。

$property = (new ReflectionClass(Account::class))->getProperty('displayId');

if (method_exists($property, 'isVirtual') && $property->isVirtual()) {
    echo "skip persistent field\n";
}

if (method_exists($property, 'getHooks')) {
    $hooks = $property->getHooks();
    echo implode(',', array_keys($hooks));
}

这类能力探测适合放在反射适配层，不要把 PHP 版本号硬编码成唯一条件。运行环境可能启用了不同的扩展或使用了多套 PHP CLI/FPM，最终应以方法是否存在和实际返回值为准。

兼容旧版本时的三个边界

不要在 PHP 8.3 上直接调用新方法

在旧版本中，ReflectionProperty 没有 isVirtual()。直接调用会产生未定义方法错误，因此要把 method_exists() 放在调用前。

virtual 不等于 public，也不等于安全

虚拟属性仍可能是 public、protected 或 private；它也不代表返回值可以无条件暴露。序列化、日志和 API 输出仍需单独做可见性、敏感字段和权限判断。

不要用 isVirtual 推断 hook 顺序

isVirtual() 只说明是否有底层存储。需要了解 hook 类型时用 hasHook() 或 getHooks()，并把 getter、setter 的业务副作用当作独立问题处理。

把判断接到导出器里的推荐写法

foreach ($reflection->getProperties() as $property) {
    if (method_exists($property, 'isVirtual') && $property->isVirtual()) {
        continue;
    }

    if (!$property->isPublic()) {
        continue;
    }

    $data[$property->getName()] = $property->getValue($object);
}

这个顺序表达了一个实用策略：先排除没有存储的计算属性，再处理可见性，最后读取值。若业务希望把计算属性作为响应字段，就不要把它混进持久化字段扫描器，而是为响应 DTO 单独声明允许输出的属性。

常见问题

没有 hook 的普通属性会返回 true 吗？

不会。官方示例明确把没有 hook 的普通属性判定为非 virtual。

只有 get hook 的属性一定是 virtual 吗？

不一定要靠“只有 get”这句话猜。关键是 hook 是否引用了该属性自身的存储；用 PHP 8.4 的 isVirtual() 读取最终语义更可靠。

PHP 8.3 项目怎么兼容这段代码？

在调用前用 method_exists($property, 'isVirtual') 探测。旧版本无法识别虚拟属性时，应保守地沿用原有字段白名单，而不是把所有反射属性都自动导出。

小结

属性钩子把“字段”和“计算值”放到了同一套声明语法里，反射工具因此需要补上存储语义判断。ReflectionProperty::isVirtual() 适合放在序列化、表单映射和文档生成的入口处：先识别 virtual，再按业务规则处理可见性、权限和敏感数据，兼容旧版本时用能力探测兜底。