PHP 8.4 非对称可见性 public private(set)：只读接口与内部写入怎么拆

订单状态经常遇到很别扭的权限冲突：列表展示和接口返回时需要对外暴露可读，唯独订单对象内部的状态机逻辑才能修改它的值。PHP 8.4 的非对称可见性用 public private(set) 把读权限和写权限完全拆开，调用方仍然可以写成 $order->status，但类外直接赋值的操作会直接被拦截。

为什么订单状态需要拆分读写权限

如果把状态声明成普通的 public 属性，控制器、序列化器甚至单元测试代码都能直接写入 paid、cancelled 或者完全不存在的非法状态。改成 private 之后，外部读取又只能额外写一层 getter 方法。大量简单属性因此多了一对只做参数转发的冗余方法。

PHP 8.4 引入的非对称可见性特性，允许为同一个属性分别声明读操作和写操作的可见性。典型的订单状态属性可以这样写：

status !== OrderStatus::Pending) {
            throw new LogicException('only pending order can be paid');
        }
        $this->status = OrderStatus::Paid;
    }
}

外部代码可以正常读取 $order->status，但不能直接执行 $order->status = OrderStatus::Paid。markPaid() 在类内部运行，持有 private set 的操作权限，可以合法完成状态迁移。

public private(set) 和 readonly 不是一回事

readonly 强调初始化完成后不能再次写入，而 private(set) 强调的是哪些代码范围可以执行写入操作。订单状态会从 pending 流转到 paid，因此 readonly 完全不适合这个场景；用户 ID 或者创建时间这类只会初始化一次的值，才更贴近 readonly 的语义。

set 可见性如何限制状态流转

非对称可见性只解决「谁能写」的问题，不会自动判断状态能不能直接从 pending 跳到 cancelled。业务流转规则仍然要放在专属方法里，方法先校验当前值，再执行一次受控的写入操作。

final class Shipment
{
    public private(set) string $state = 'created';

    public function dispatch(string $trackingNo): void
    {
        if ($this->state !== 'created') {
            throw new LogicException('shipment is not ready');
        }
        if ($trackingNo === '') {
            throw new InvalidArgumentException('tracking number is required');
        }
        $this->state = 'dispatched';
    }
}

这类写法的核心是把状态变更逻辑全部集中在命名方法中。审计日志、事件发布和数据库更新操作可以紧跟在赋值逻辑后面处理，调用者完全感知不到属性内部的写权限限制。

接口和继承：先看契约，再看修饰符

接口可以只描述一个公开可读的属性，不需要要求实现类把写权限也同步对外开放：

interface HasStatus
{
    public OrderStatus $status { get; }
}

final class Payment implements HasStatus
{
    public private(set) OrderStatus $status = OrderStatus::Pending;
}

实现类的 public read 权限完全满足接口要求，private set 不会破坏「外部可读」的对外契约。反过来，如果接口要求 public set 权限，实现类不能用 private set 把写权限收窄，否则会导致原有调用逻辑直接失效。

继承也要遵守同一个原则：子类不能把父类已经承诺的外部写权限改成更窄的权限，否则已有调用方的代码会直接报错。准备升级旧类的时候，先用静态分析工具检查父子类的属性声明，再逐个核对接口定义。

常见误区：把权限控制当成业务校验

private(set) 不会替你校验值的合法性

它只限制写入发生的代码位置。类内部仍然可能写出不符合预期的错误状态，所以每个对外公开的状态变更方法都要自己做好前置条件判断和异常抛出策略。

不能通过版本判断包住新语法代码

PHP 8.3 解析类文件的时候就会遇到不认识的属性修饰符，代码还没执行到 PHP_VERSION_ID 版本判断逻辑就已经报错终止。需要同时支持 PHP 8.3 的场景下，应该使用独立的兼容类、构建产物分流方案，或者保留私有字段加 getter/setter 的旧实现方式。

final class LegacyOrder
{
    private OrderStatus $status = OrderStatus::Pending;

    public function status(): OrderStatus
    {
        return $this->status;
    }

    public function markPaid(): void
    {
        if ($this->status !== OrderStatus::Pending) {
            throw new LogicException('invalid order transition');
        }
        $this->status = OrderStatus::Paid;
    }
}

上线前怎么验收读写边界

• 类外读取 status，确认序列化操作和日志输出仍然可以正常拿到当前状态。
• 在类外尝试直接赋值，确认抛出的失败类型和错误信息符合项目的统一约定。
• 通过 markPaid()、取消或发货方法覆盖所有允许和禁止的状态迁移场景。
• 检查接口、trait 和子类有没有把 set 权限意外放宽或者收窄的情况。
• 在 PHP 8.3 的构建链路跑一遍兼容实现，避免新语法代码混入面向旧版本的部署产物里。

常见问题

public private(set) 能不能从子类写入？

private set 只在声明属性的当前类内部可写；如果子类也需要修改这个属性，应该重新设计为 protected set，或者通过父类提供的受控方法来修改。

public private(set) 和 public protected(set) 怎么选？

状态只能由父类方法维护时选 private set；允许整个继承体系扩展状态迁移逻辑时才考虑用 protected set，同时要同步做好子类的权限边界检查。

接口能否只声明可读属性？

可以。接口用 get 关键字约束外部读取权限，实现类可以用普通 public 属性、readonly 属性或者带更窄写权限的属性来满足这个约束。

PHP 8.3 项目怎么渐进迁移？

先稳定方法形式的领域接口，再准备 PHP 8.4 专用的实现；确认所有部署环境全部升级之后，才把调用方代码改回直接属性访问的形式。

非对称可见性非常适合表达「对外可观察、内部做修改」的对象状态，但它不会替代状态机、参数校验和审计逻辑。把写入口收拢到命名方法里，再用 public private(set) 暴露读取权限，通常能在代码可读性和规则约束力之间找到更稳妥的平衡。