PHP readonly对象承载不可变配置的设计要点

配置对象最怕“读取时还能被悄悄改掉”。PHP 8.1 起可以把属性声明为 readonly：构造阶段完成校验和赋值，之后只能读取；PHP 8.2 起还可以把整个类声明为 readonly class。因此，应用配置适合先从数组转成经过校验的对象，再把对象注入服务，而不是让各层直接共享原始数组。

官方文档：https://www.php.net/manual/en/language.oop5.properties.php

构造阶段完成校验，配置对象只负责读取

先把外部输入变成局部变量并完成边界检查，再对只读属性做直接赋值。属性必须有类型；同一个属性只能在声明它的作用域内初始化一次，后续赋值、引用写入或 unset() 都会触发错误。

 */
    public readonly array $allowedHosts;

    public function __construct(array $raw)
    {
        // 先校验输入，避免把不完整配置传播到服务层。
        $dsn = trim((string) ($raw['dsn'] ?? ''));
        $timeoutMs = (int) ($raw['timeout_ms'] ?? 0);
        $allowedHosts = array_values(array_filter(
            $raw['allowed_hosts'] ?? [],
            static fn (mixed $host): bool => is_string($host) && $host !== ''
        ));

        if ($dsn === '' || $timeoutMs  30000) {
            // 失败时不创建半成品对象，让启动错误尽早暴露。
            throw new InvalidArgumentException('配置参数不合法');
        }

        // 只在构造阶段直接写入 readonly 属性。
        $this->dsn = $dsn;
        $this->timeoutMs = $timeoutMs;
        $this->allowedHosts = $allowedHosts;
    }
}

$config = new AppConfig($envConfig);
// 后续代码只读取稳定值，不再修改配置对象。
$clientTimeout = $config->timeoutMs;

属性只读不等于对象深度不可变

把数组存进 readonly 属性后，不能再改数组元素；但如果属性保存的是一个对象，readonly 只限制属性指向不能换成另一个对象，不会自动禁止那个对象自己的可变方法。因此连接池、可变集合或服务实例不要直接当作“不可变配置”暴露，宜改成标量、数组或同样经过约束的值对象。

按 PHP 版本选择属性写法与兼容方案

项目最低版本为 PHP 8.1 时，继续为每个属性显式写 public readonly，最容易控制字段范围。最低版本为 PHP 8.2 时，可以使用 readonly class，它会把实例属性整体设为只读，并阻止动态属性；类中仍不能声明静态或无类型属性。

name === '' || $this->maxRetries 

迁移时不要只把关键字批量替换进去：先确认运行时版本，再检查反射、序列化、ORM 填充和克隆逻辑是否会尝试二次写入。配置对象的职责是承载稳定结果，不是替代配置加载器或运行时状态容器。

常见问题

readonly 属性可以声明默认值吗

通常不可以。它应该在构造阶段直接初始化；若固定值无需实例状态，使用类常量更合适。

readonly 能冻结嵌套对象吗

不能。它限制属性本身重新指向对象，嵌套对象仍需自己的不可变设计或复制策略。

PHP 8.1 能直接写 readonly class 吗

不能。readonly class 从 PHP 8.2 开始可用，PHP 8.1 应改用逐个 readonly 属性的写法。