#PHPreadonly类与只读属性实战:用不可变对象根治"对象被偷偷改了"的玄学Bug先说个丢人的事。去年十一月赶一个订单结算模块,我连着两个晚上熬到一点多,就为了抓一个现在回头看特别蠢的Bug:同一个`$order`…
PHP readonly 类与只读属性实战:用不可变对象根治"对象被偷偷改了"的玄学 Bug
PHP readonly 类与只读属性实战:用不可变对象根治"对象被偷偷改了"的玄学 Bug
先说个丢人的事。
去年十一月赶一个订单结算模块,我连着两个晚上熬到一点多,就为了抓一个现在回头看特别蠢的 Bug:同一个 $order对象,传进优惠计算函数之前amount还是19900,函数一返回,回到主流程再打一次日志,变成18900了。中间没有一处显式赋值,我把amount这个关键词全局搜了八遍,写操作一处都没多出来。
那两天我是真的一点排查思路都没有。本地跑、测试环境跑,金额都正常得不能再正常;一上预发就复现,还挑订单。我一度怀疑是缓存串了,把 Redis 键值翻了个底朝天;又怀疑是并发写库,盯着慢查询日志看了半宿。甚至低到开始怀疑人生:是不是日志本身打错了?直到我把优惠服务单独拎出来,在入口和出口各打一行 $order->amount,才看见同一个对象在函数调用前后判若两人。那种感觉很难形容——你一直以为问题在外面,结果它就藏在你亲手递出去的那个对象里。
最后发现是隔壁组新来的同学在优惠服务里图省事,写了这么一句——
php// 优惠服务里"顺手"把传进来的订单对象改了// 注意:PHP 对象传的是对象句柄,这里一改,调用方手里的同一个对象也跟着变了$order->amount = $order->amount - 1000;
就这么一句。PHP 的对象变量传的是"对象句柄",你可以粗略理解成一个指向同一块内存的身份牌,不是值拷贝。函数里动了它,外面看到的就是动完之后的它。这道理不难,可当它藏在一个几百行的调用链里,你盯着所有给 amount赋值的语句看一整天都未必定位得到——因为问题压根不在"哪句赋值",而在于这个对象本来就不该有被赋值的资格。
那天凌晨合上电脑我就在琢磨:有没有办法让对象一旦造出来就锁死,谁想改当场报错,最好连"改"这个念头都在引擎那一层就被掐掉。
有,这就是 PHP readonly。
一句话概括:PHP 8.1 的
readonly只读属性、PHP 8.2 的readonly class只读类,把"不可变"从开发者之间的君子协定,变成了引擎层面强制执行的事实——用不可变对象和值对象,把"对象被偷偷改了"这类玄学 Bug 直接摁死在摇篮里。

readonly 出来之前,我是怎么"假装"对象不可变的
我入行那会儿,PHP 还是 7.x 的天下,根本没有 readonly 这回事。想让一个属性不可变,标准套路是三板斧:属性设成 private,构造函数里赋值,然后只对外暴露 getter。
php<?php// 老写法:private 属性 + public getter,靠"约定"实现只读class Order{ // 属性私有,外部直接访问会报"不能访问私有属性" private int $amount; public function __construct(int $amount) { // 只能在构造阶段赋一次值 $this->amount = $amount; } public function getAmount(): int { // 外部只能读,没法写 return $this->amount; }}$order = new Order(19900);echo $order->getAmount(); // 19900// $order->amount = 100; // 报错:Cannot access private property Order::$amount
这套能跑,也确实挡住了绝大多数手滑。但它有三个我越来越受不了的地方。
一是样板代码多。每个想只读的属性都得配一个 getter,一个 DTO 有十来个字段,就得写十来个 getXxx(),纯体力活。二是它只是"约定",不是"强制"。真有人在本类的方法里手滑改了一句$this->amount = ...,编译器一声不吭,测试没覆盖到就溜进生产了。三是反射和序列化能绕过去。ReflectionProperty::setValue() 招呼一声,private 也拦不住。
我那时候还试过用__get/__set魔术方法模拟只读,结果更糟。__set 拦不住对 public 属性的直接赋值,除非你把属性设成 private 再全套走魔术方法——那代码量比 getter 还夸张,而且每次属性访问都过一遍魔术方法,高频调用场景下的开销肉眼可见。之前写 HTML Popover API 实战:不写一行 JS 也能做原生弹窗(popover 属性与 Top Layer 层叠上下文)时我就有过类似的感慨:浏览器原生给了Top Layer 这种能力,你非要拿一堆 JS 和 z-index 去手动模拟,费劲不说,还到处是洞。语言层面原生支持的不可变,跟自己拿魔术方法搓出来的"仿制品",完全不是一回事。
readonly 属性:PHP 8.1 把"别改我"写进了引擎
PHP 8.1 引入了 readonly修饰符。它做的事情说白了特别朴素:给属性打上"初始化之后不许再写"的标记,而且这条规矩是引擎替你守的。
php<?php// PHP 8.1+:readonly 属性 + 构造函数属性提升,两行搞定只读字段class Money{ public function __construct( // 提升出来的属性直接标 readonly,声明 + 赋值一步到位 public readonly int $cents, public readonly string $currency, ) {}}$money = new Money(19900, 'CNY');echo $money->cents; // 19900,随便读echo $money->currency; // CNY// 下面这行一执行就炸,注意是 Error,不是 Warning// $money->cents = 20000;// Fatal error: Uncaught Error: Cannot modify readonly property Money::$cents
这段代码里有个细节我特别喜欢:readonly 属性是实例级别的。同一个类造出来的两个对象,可以各自持有不同的 readonly 值,互不干扰。这跟 const完全不一样——const是类级别的,所有实例共享,而且必须在编译期就能确定值(你写const CREATED_AT = time();直接报错,因为time()是运行期才知道的)。
readonly 的几条硬规矩,我踩过坑之后是这么记的:
- 必须有类型声明。写
readonly $x直接编译错误。实在类型不确定,就显式写readonly mixed $x——注意是mixed也得写出来,不能省。 - 不能用于静态属性。你写
public static readonly int $count;引擎会告诉你 readonly static 不支持。静态的那部分不可变需求,老老实实用const。 - 只能在声明它的作用域里初始化一次。在构造函数里赋初始值合法;出了这个类从外部赋,报错
Cannot initialize readonly property ... from global scope。 - 只能直接赋值。想通过引用初始化(比如
preg_match()第三个参数直接塞进 readonly 数组属性)也不行,会报Cannot indirectly modify readonly property。这个坑我踩过一次,排查了半天才发现是"间接赋值"触了红线。
还有一个反直觉的点:赋一样的值也算改。我第一次写的时候想当然,觉得$money->cents = 19900(跟原值一模一样)应该能过吧?不行,Error照样甩脸上。引擎判断的是"你有没有执行写操作",不是"值变没变"。这个设计我觉得挺对——如果允许写同值,那"不可变"就变成"看起来没变",等于又回到靠约定的老路了。
还有个我一开始没想明白、后来被实战教育的问题:readonly 属性既然"只能在声明它的作用域里初始化一次",那我在构造函数里初始化之后,类内部的其他普通方法还能不能碰它?答案是——读随便读,写一律不行。我试过在一个 recalculate() 方法里想给 readonly 属性重算赋值,直接 Error。这才是对的:readonly 的"作用域"限制说的是谁能做第一次赋值(本类构造函数里可以,全局作用域不行),不是"本类以后还能反复改"。很多人把这两句话混成一句,以为"本类内部随便改",那就理解反了。想改怎么办?两种正规路子:要么在构造之前把值算好再传进来,要么像值对象那样返回一个新实例。只有clone 那条口子在 8.3 之后开了个小例外,那也是针对"新对象"的一次性初始化,跟原地修改是两码事。
最大的坑:readonly 只锁"引用",不锁"对象内部"
这条是我认为最值得单独拎出来讲的,因为它是 readonly 最容易让人翻车的地方,也是很多人以为"用了 readonly 就万事大吉"的最后一道坎。
readonly 保证的是:这个属性不能再指向别的东西。它管不了"这个属性指向的那个对象,内部字段能不能改"。看个血淋淋的例子:
php<?php// ◆ 反面教材:readonly 里塞了一个"可变"对象class Event{ public function __construct( // DateTime 是可变对象!它自己的 modify() 会改内部状态 public readonly DateTime $createdAt, ) {}}$event = new Event(new DateTime('2026-11-20 10:00:00'));// 你改不了 $event->createdAt 这个"槽位"本身:// $event->createdAt = new DateTime(); // Error: Cannot modify readonly property// 但这个槽位指向的对象,你可以随便揉搓:$event->createdAt->modify('+1 day');echo $event->createdAt->format('Y-m-d H:i:s'); // 时间已经被偷偷改了一天!
看见没?$event->createdAt->modify('+1 day') 这行完全合法,readonly 一点脾气没有。因为从引擎视角看,你并没有给 createdAt属性重新赋值,你只是"隔着这个属性,调了它所指对象的一个方法"。对象内部状态变了,属性的引用没变。
这就是interior mutability(内部可变性)。想真正锁死,必须让 readonly 属性指向一个本身也不可变的对象——DateTimeImmutable就是为此而生的:
php<?php// ◆ 正确姿势:readonly + 不可变对象类型,双保险class Event{ public function __construct( // DateTimeImmutable 的 modify() 不修改自己,而是返回一个新对象 public readonly DateTimeImmutable $createdAt, ) {}}$event = new Event(new DateTimeImmutable('2026-11-20 10:00:00'));// modify() 返回新实例,原对象纹丝不动;这里必须显式接住返回值$nextDay = $event->createdAt->modify('+1 day');echo $event->createdAt->format('Y-m-d'); // 2026-11-20,原对象没被改echo $nextDay->format('Y-m-d'); // 2026-11-21,改动落在新对象上
所以我的经验是:readonly 属性里如果装的是对象,一定确认那个对象类型本身是不可变的。装DateTime就是给自己埋雷,装DateTimeImmutable才踏实。
数组这块得单独说道说道,因为它是另一类高频翻车现场。readonly 属性装一个数组,你确实不能再给它整体赋值一个新数组,但 $obj->items[] = 'x'、unset($obj->items[0])、甚至$obj->items[0]['k'] = 'v' 这种嵌套修改,引擎统统拦不住。8.1 那会儿我被这个坑得挺惨:一个标了 readonly 的配置数组,自以为锁死了,结果运行两小时后发现某个业务分支往里塞了脏数据,因为向量是在原数组上直接追加的。后来我的处理办法就一条——凡是要往外暴露的集合,getter 里返回副本,或者干脆别用裸数组,封装成一个自带不可变语义的集合对象,外部想加元素只能拿到一个"加了之后的新集合"。多写几行,但晚上睡得着。
说白了,readonly 锁的是"这个变量指向哪",不是"这个变量指向的东西长什么样"。你要的是后者,就得把那个"东西"本身也设计成不可变的。这两层缺一层,所谓的不可变都是自欺欺人。
这跟我在CSS Subgrid 实战:用网格继承让嵌套布局严丝合缝对齐(subgrid 与 grid-template-rows/columns) 里强调的那件事有点像:表面上有"继承"关系不代表子级就老老实实跟着走,你得把约束真正落到每一层的定义上,不然看着对齐了,稍微一变就散架。readonly 是第一层约束,属性里那个对象的类型,是第二层。两层都做对,才叫真的不可变。
readonly class:PHP 8.2 让整个类天生不可变
PHP 8.2 往前迈了一大步:直接把整个类标成 readonly。
含义特别直接——类里声明的每一个属性,自动都带上 readonly,不用你一个一个加。刚才那个Money类,用只读类重写是这样:
php<?php// PHP 8.2+:readonly class,类内所有属性自动只读readonly class Money{ public function __construct( // 注意这里没有写 readonly,但因为是 readonly class,属性依然是只读的 public int $cents, public string $currency, ) {} public function format(): string { // 类内部可以正常读取自己的属性 return ($this->cents / 100) . ' ' . $this->currency; }}$money = new Money(19900, 'CNY');echo $money->format(); // 199 CNY// $money->cents = 1; // 照样 Fatal error:Cannot modify readonly property
readonly class 的几条限制得记牢,我一条条都撞过:
- 属性必须有类型。类里写个
public $bar;无类型属性,直接Fatal error: Readonly property Foo::$bar must have type。 - 不能有静态属性。写
public static int $bar;,报Fatal error: Readonly class Foo cannot declare static properties。原因也好理解——静态属性本质上是"类级别"的,跟 readonly 强调的"实例不可变"天生拧巴。 - 不能创建动态属性。普通的 PHP 8.2 类往不存在的属性上赋值只是个弃用警告,readonly class 直接编译期禁止,而且你连
#[\AllowDynamicProperties]这个逃生通道都用不了,标上去就是Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class。 - 继承是单向锁死的。readonly class 可以被继承,但子类必须也是 readonly class。你拿一个普通 class 去继承 readonly 父类,直接编译错误。反过来,普通父类可以被 readonly 子类继承吗?可以,但子类自己声明的属性照样得满足只读那套规则。
关于"readonly class 只能是没有构造函数的纯数据类"这种说法——我看到过好几个教程这么写,这是错的。官方发布页的示例里明明白白带着构造函数,readonly class 完全可以、而且经常需要构造函数来初始化属性。别被那类说法带偏了。我猜这个误传是从"动态属性被禁"那条例外衍生出来的:因为 readonly class 连 #[\AllowDynamicProperties]都禁了,有人就误以为它"啥都不让做",只剩个空壳数据袋。其实限制的只是"属性怎么来的"(必须声明、必须有类型、必须构造阶段初始化),不是"能有多少行为"。方法、构造函数、接口实现,一样都不少。我自己的值对象里就塞了一堆withXxx()、equals()、format()方法,用得好好的。
继承那条也补个真实场景。我们有两类金额:Price(普通金额)和TaxIncludedPrice(含税金额),一开始我想让后者继承前者,写了个普通类继承 readonly 父类,CI 直接编译错误,卡了我二十分钟。后来才反应过来规则是"readonly 的子类才能继承 readonly 父类"——把子类也声明成 readonly class就通过了。这个约束初看有点烦,其实是在保护你:如果允许一个可变子类继承不可变父类,那父类辛辛苦苦守住的"不可变",子类随手一个public $cents;就全毁了。锁死继承链,是让不可变性不会被后代破坏。
值对象实战:我用 readonly class 重写了订单金额
回到开头那个 Bug。我最后的解法,就是把这个金额相关的结构改成了值对象(Value Object),用 readonly class 承载。
值对象的核心思想一句话:它描述的是"一个值",不是"一个可变的东西"。金额 199 分就是 199 分,它不该有"被改成 189 分"这种说法——想要 189 分,你应该造一个新的金额对象,而不是把旧的那个改掉。
php<?php// 一个真正不可变的金额值对象readonly class Price{ public function __construct( public int $cents, // 金额,单位:分,避免浮点误差 public string $currency, // 币种 ) {} // 打折不修改自身,而是返回一个全新的 Price 实例 public function withDiscount(int $percent): self { if ($percent < 0 || $percent > 100) { // 值对象在构造/运算时做校验,保证任何实例都是合法的 throw new InvalidArgumentException('折扣百分比必须在 0 到 100 之间'); } $discounted = (int) round($this->cents * (100 - $percent) / 100); return new self($discounted, $this->currency); } // 相加同样返回新实例 public function add(self $other): self { if ($this->currency !== $other->currency) { // 不同币种不能直接相加,这也是值对象帮你守住的业务不变量 throw new InvalidArgumentException('币种不同,无法相加'); } return new self($this->cents + $other->cents, $this->currency); }}$price = new Price(19900, 'CNY');$sale = $price->withDiscount(10); // 得到一个新对象:17910 分$total = $sale->add(new Price(500, 'CNY'));echo $price->cents; // 19900,原价对象从头到尾没被动过echo $sale->cents; // 17910echo $total->cents; // 18410
改完之后,开头那种"传进去之前 19900、传完之后 18900"的事情就再也不可能发生了。因为优惠函数拿到一个 Price,它没有任何办法把里面的cents改掉——想打折?调用withDiscount()拿新对象去。你就算把对象传进十个服务里轮番折腾,出来还是原来那个值。
顺带一提,我在这个项目里还配合Compression Streams API 实战:用浏览器原生 gzip/deflate 压缩数据流(CompressionStream 与 DecompressionStream)里那套"数据一旦定型就不再回头改"的思路整理了前端的报价展示逻辑:后端给出的值对象序列经过压缩流推给浏览器,前端只负责渲染,不碰数值本身。前后端都守着"不可变"这一个原则,联调的时候少扯了好多皮。
clone、报错信息,还有那些文档角落里的细节
真正上线之后,我又陆续碰到几个不在主流程里的边角问题,一起记在这儿。
clone 时重新赋值(PHP 8.3+)。 8.3 之前,readonly 属性一旦初始化,连 clone 出来的新对象都没法给它重新赋值。8.3 放开了这个口子:你可以在 __clone() 里给 readonly 属性重新赋一次值,而且这次赋值只影响克隆出来的新对象。
php<?php// PHP 8.3+:__clone() 里可以给 readonly 属性重新初始化class Snapshot{ public readonly DateTimeImmutable $createdAt; public function __construct() { $this->createdAt = new DateTimeImmutable('now'); } public function __clone() { // 克隆出来的对象,时间戳重置为克隆这一刻 // 这个重新赋值只在 PHP 8.3+ 合法 $this->createdAt = new DateTimeImmutable('now'); }}$original = new Snapshot();$copy = clone $original;// $copy 的 createdAt 是克隆时刻,$original 的仍是构造时刻
8.4 的小变化。 从 PHP 8.4 开始,readonly 属性在可见性上隐含了 protected(set) 的语义——意思是子类也能给它赋值了(8.4 之前 readonly 隐含 private-set,只有本类能写)。如果你在项目里跨版本跑,这条得留个心眼,别以为"readonly = 谁都写不了",8.4 之后子类是有机会写的。
报错信息要认得。 调试时看到这几句别慌,它们都是 readonly 在正常工作:
Cannot modify readonly property Foo::$bar—— 初始化之后又想改,最常撞的。Cannot initialize readonly property Foo::$bar from global scope—— 在类外面试图第一次赋值。Cannot indirectly modify readonly property—— 用引用或preg_match()之类间接写入。Readonly class Foo cannot declare static properties—— 只读类里想放静态属性。
版本兼容要提前说清。 PHP 8.0 及更早的版本根本不认识 readonly 这个关键字,脚本会直接解析失败,不是"忽略",是"当语法错误处理"。所以你要是在给一个还跑着 7.4 的老项目加 readonly,第一步是推动升级,而不是硬写。这个坑我们组去年就踩过,代码合并到一条 7.4 的发布分支上,CI 直接红了一片。
const、final、readonly,别再混着用了
这仨我见太多人搞混了,尤其是刚接触 PHP 8 新特性的同事。简单粗暴地分一下:
const是类常量,属于类不属于实例,所有实例共享一份,而且值必须在编译期就能确定。存实例数据(比如每个订单各自的创建时间)用它就错了。final修饰的是类或方法,意思是"不能被继承"或"不能被重写",跟属性能不能改半毛钱关系没有。很多人以为final class里面的属性就安全了——不,该改还是能改。readonly修饰的是属性或类,管的是"实例持有的一份数据,初始化后不能再被重新赋值"。这才是我们这篇文章要的东西。
有个误区我得点出来:有人觉得把属性设成private、再给个final public function getX()就高枕无忧了。并不是——private 属性照样能被反射、能被序列化流程篡改。真要引擎级兜底,还是得靠 readonly。这几者的关系,有点像 WebTransport API 实战:基于 HTTP/3 的低延迟双向通信(datagram 数据报与 stream 流) 里 datagram 和 stream 的分工:看着都能传数据,但一个管"快速、无序、一次性的消息",一个管"可靠、有序、成组的字节流",职责完全不同,混着用迟早出问题。
什么时候用 readonly,什么时候别碰
我不喜欢"任何场景都上 readonly"这种话,太绝对。说说我自己的取舍。
大胆用的地方:DTO(接口返回的数据结构)、值对象(金额、坐标、日期区间)、配置对象、事件对象、枚举配合的不可变结构。这些对象的共同点是"描述一个事实/一个值",创建之后就不该变。用 readonly 之后,代码意图一眼就清楚,还能少写一堆 getter。
别硬用的地方:ORM 的实体(Entity)。Doctrine 这类 ORM 依赖对象可变来追踪变更、做脏检查,你给实体属性全标 readonly,等于断了 ORM 的活路。还有需要延迟初始化的属性、需要被框架依赖注入二次赋值的字段,也得绕开。一句话:业务上本来就要经历状态流转的东西,别拿 readonly 去锁。
性能上不用担心。readonly 是引擎层的约束,没有 __get/__set那种每次访问都过一遍魔术方法的开销,读性能和普通属性一样。这是我实测过的,高频读取循环里几乎看不出差别。
配合静态分析工具效果翻倍。我们项目里跑了 PHPStan,把属性标成 readonly 之后,它在编译前就能提示"这里不该给 readonly 属性赋值",把问题拦在提交阶段,比等到运行时抛 Error再查堆栈舒服太多。这也是魔术方法模拟方案给不了的——工具看不懂__set背后的意图,但readonly 这个关键字它是认识的。我现在的习惯是:改一个老类之前,先问自己"这个属性这辈子该不该变",答案是否,就顺手补上 readonly,让工具和引擎一起帮我盯着。这个习惯养成的成本很低,但后面省下来的排查时间,是实打实的。
版本这块我的建议很实在:项目能上 8.2,就优先用 readonly class 定义值对象和 DTO,一行顶过去一堆模板代码;只能上 8.1,就用 readonly 属性加构造函数提升;还在 7.4 的,别纠结了,先把升级排进计划。
回到开头那个凌晨一点的我。如果当时就知道 readonly,那两个通宵本来是可以省下来的——Del 键删掉那句"顺手改一下",把 Order 的金额换成不可变的值对象,Bug 从根上就不存在。所谓"玄学 Bug",很多时候不是它真的玄,而是我们给了对象太多本不该有的自由。把自由收回来,世界清静多了。
标签:PHP readonly, readonly class, 只读属性, 不可变对象, 值对象描述:通过真实踩坑经历讲解 PHP 8.1 readonly 只读属性与 PHP 8.2 readonly class 的用法,涵盖初始化规则、内部可变性陷阱、值对象实战、clone 与继承限制、版本兼容等要点,教你用不可变对象根治"对象被偷偷改了"的玄学 Bug。

发表评论发布评论后审核成功,即可显示在列表中...