PHP ReflectionProperty 读取 readonly 属性时有哪些限制

在序列化器或对象映射器里用 ReflectionProperty 读取 PHP 属性时，最容易踩的坑不是 private，而是把“声明为 readonly”和“当前实例已经初始化”混成一件事。PHP 8.1 以后，反射可以直接读取 private、protected 属性；但未初始化的 typed property 仍然不能被 getValue() 当作普通的 null 读取。

一、先把 readonly 和初始化状态拆开判断

readonly 是属性的声明约束：它只能被初始化一次，初始化以后不能重新赋值。它不代表属性一定已经有值。例如构造函数没有给某个 readonly 属性赋值时，对象仍然可以创建，但这个属性处于未初始化状态。

所以，反射读取流程应该先记录两个布尔值，再决定是否取值。只看 isReadOnly() 会漏掉普通 typed property 的未初始化情况；只看 isInitialized() 又无法知道后续代码是否可能尝试写回。

二、PHP 8.1 以后读取 private 不再靠 setAccessible

旧代码常见的写法是先调用 $property->setAccessible(true)，再调用 getValue()。从 PHP 8.1 开始，private 和 protected 属性已经可以直接通过反射读取，setAccessible() 不再改变访问结果；PHP 8.5 又将它标记为弃用。新代码可以直接移除这一步，减少版本迁移时的噪音。

但“可以读取”不等于“可以修改”。ReflectionProperty::getValue() 只取当前值，不会解除 readonly 的一次初始化约束。一个已经初始化的 readonly 属性可以被反射读取，仍然不应该把反射当成绕过业务不变量的写入口。

id = $id;
        $this->region = $region;
        $this->label = '待命名';
    }
}

$account = new Account('A-100', '华东');
$reflection = new ReflectionClass($account);

foreach (['id', 'region', 'label'] as $name) {
    $property = $reflection->getProperty($name);

    // PHP 8.1+ 不需要 setAccessible() 才能读非 public 属性。
    $value = $property->getValue($account);
    printf("%s: readonly=%s, value=%s\n", $name,
        $property->isReadOnly() ? 'yes' : 'no', (string) $value);
}

如果项目还要兼容 PHP 8.0 或更早版本，才需要单独讨论旧的可见性处理；不要为了兼容新版本而无条件保留已经无效的调用。

三、getValue 前必须处理未初始化属性

未初始化的 typed property 没有可返回的默认值。对它调用 getValue()，会触发类似“Typed property ... must not be accessed before initialization”的 Error。这个行为和属性实际值为 null 不一样，反射代码不能用 null 作为唯一状态标记。

note = null;
    }
}

function inspectProperty(object $object, string $name): array
{
    $property = new ReflectionProperty($object, $name);
    $initialized = $property->isInitialized($object);

    // initialized 必须和 value 分开保存，才能区分“未初始化”和“值为 null”。
    return [
        'readonly' => $property->isReadOnly(),
        'initialized' => $initialized,
        'value' => $initialized ? $property->getValue($object) : null,
    ];
}

$row = new ImportRow();
var_dump(inspectProperty($row, 'line')); // initialized=false，不读取 line
var_dump(inspectProperty($row, 'note')); // initialized=true，value=null

这也是反射型 hydrator、日志采集器和 DTO 转数组代码最应该固定下来的顺序：先确认属性属于目标对象，再确认初始化状态，最后才调用 getValue()。如果业务必须区分缺失、未初始化和显式 null，返回结构中应保留 initialized，不要只返回一个值。

四、升级反射读取代码时保留这张检查清单

迁移旧的反射工具类时，可以按下面的顺序回归：

• 属性是静态属性时，不传对象；实例属性必须传入声明类或兼容子类的对象。
• 先用 isReadOnly() 记录声明约束，再用 isInitialized($object) 判断当前对象状态。
• 已初始化后再调用 getValue()；未初始化时返回状态对象、跳过字段，或交给显式的缺省策略。
• PHP 8.1+ 删除无效的 setAccessible()；若仍需兼容 PHP 8.0，再用版本分支隔离旧调用。

还要注意，readonly 只限制属性槽位的重新赋值。若 readonly 属性存的是对象，对象内部的可变成员仍可能变化。因此日志或缓存键设计不能只看到 isReadOnly() 就断言整个对象深度不可变。

常见问题

isReadOnly() 返回 true，getValue() 就一定能读到值吗？

不一定。它只说明声明带有 readonly；对象实例可能尚未初始化。读取前仍要调用 isInitialized()。

读取 private 属性还要调用 setAccessible(true) 吗？

PHP 8.1 及以后不需要。该方法不再改变属性访问结果，PHP 8.5 起还被弃用。

没有初始化的 readonly 属性能当成 null 吗？

不能。未初始化是独立状态，直接 getValue() 会报错；用初始化标记和 value 字段分开表达。

ReflectionProperty 能绕过 readonly 修改已存在的值吗？

不能把反射当成通用解锁手段。已初始化 readonly 属性仍受一次写入约束，读取和写入应在工具设计中分开。