PHP 8.4 property hooks 如何校验金额字段：set 访问器与异常回滚

订单服务里，金额字段最怕“看起来是数字，落库时才发现单位和范围不一致”。PHP 8.4 的 property hooks 可以把这道检查放到属性写入边界：外部仍然使用 $order->amount，对象内部统一保存分为整数分的金额，并在非法写入时立即抛出异常。

把金额归一化放进 set 访问器，把跨字段的业务判断留在订单服务层；这样每次写入都能得到同一条校验路径，失败也不会悄悄留下半成品状态。

先把金额字段的用户任务说清楚

这里的任务只有一个：创建订单时接收“整数分”，之后允许修改金额，但每次修改都必须满足 0 。展示层可以把 1299 格式化成 12.99 元，领域对象不负责显示格式，也不接受浮点数参与计算。

PHP 8.4 官方说明把 property hooks 定义为拦截属性读写的 get 和 set 行为。它适合做字段自身稳定的约束；订单是否已支付、是否允许改价，则需要订单状态，不能只看一个数。

用 set 访问器固定 amount 的单位和范围

下面的 OrderAmount 只保存整数分。amount 是带存储值的属性，set 收到新值后先检查类型约束允许的整数，再检查范围，最后通过 $this->amount = $value 写回归一化后的值。

 100000000) {
                throw new InvalidArgumentException('amount out of range');
            }

            $this->amount = $value;
        }
    }

    public function __construct(int $amount)
    {
        $this->amount = $amount;
    }
}

$price = new OrderAmount(1299);
$price->amount = 1599;
echo $price->amount; // 1599

构造函数的赋值同样经过 set，所以入口不会出现“创建时校验一套、更新时校验另一套”的分叉。运行检查时应看到初始值为 1299，改写后为 1599；如果传入负数，程序应在赋值表达式处终止并报告 amount out of range。

异常发生时为什么不会覆盖旧金额

set 里的顺序很关键：先判断，再写回。假设当前金额是 1599，下一次写入 -1，InvalidArgumentException 在 $this->amount = $value 之前抛出，因此对象里的合法值仍是 1599。这个“先校验、后提交”的边界就是最小的异常回滚。

amount = -1;
} catch (InvalidArgumentException $error) {
    echo $error->getMessage(); // amount out of range
}

echo $price->amount; // 1599

这里不要在钩子里捕获异常再返回 0。那会把调用方的错误输入改成一个看似合法的金额，后续很难从日志判断问题来源。需要统一记录上下文时，可以在订单服务层捕获异常并补充订单号，但不要改变对象的失败语义。

跨字段规则应该放在哪里

单字段规则可以在 set 中完成：金额必须是整数、不能为负、不能超过上限。下面这些判断则不属于 amount 自己：订单进入 paid 状态后不能改价；退款金额不能超过已支付金额；人民币和外币要使用不同精度。

更稳妥的分层是：属性钩子保护数值本身，OrderService 根据订单状态和币种做业务决策，数据库事务负责最终提交。这样钩子不需要读取尚未初始化的兄弟属性，也不需要查询数据库。

PHP 8.3 项目怎样保留同一个契约

property hooks 从 PHP 8.4 引入。如果线上仍是 PHP 8.3，可以把同样的检查收回私有方法，保持调用方的“整数分、非法值抛异常、失败保留旧值”契约，等运行时升级后再替换语法。

setAmount($amount);
    }

    public function amount(): int
    {
        return $this->amount;
    }

    public function change(int $amount): void
    {
        $this->setAmount($amount);
    }

    private function setAmount(int $value): void
    {
        if ($value  100000000) {
            throw new InvalidArgumentException('amount out of range');
        }
        $this->amount = $value;
    }
}

迁移测试只需要锁定三个结果：1299 能创建；1599 能更新；-1 抛出异常且读取结果仍是上一次合法值。不要把“使用了 property hooks”当作测试目标，真正需要守住的是金额对象的行为。

常见问题

金额为什么不建议用 float？

浮点数存在二进制表示误差，订单金额通常用整数分或专用 decimal 类型。本文的 amount 约定为整数分，展示时再转换为元。

set 里可以访问订单状态吗？

技术上可以访问，但会让单字段写入依赖对象初始化顺序。支付状态、退款上限等规则应放在服务层或领域方法。

异常后属性一定保持旧值吗？

只有在校验完成前没有执行写回时才成立。先校验、后赋值，并用测试覆盖异常路径，才能保证这个契约。

把金额校验收束成可复查的边界

property hooks 的价值不在于省掉几个 getter，而在于让属性写入经过一条可见、可重复的规则链。对金额字段，先明确整数分单位，再在 set 中做局部校验和写回；订单状态、币种和事务交给更高一层。上线前复查合法写入、非法写入和异常后的旧值，基本就能抓住这类改价 bug。