Eloquent Attribute Transformation 是模型序列化为数组或 JSON 时对属性值的单向格式转换，仅作用于 toArray()/toJson()，不影响内部存储、查询或填充逻辑。
什么是Eloquent Attribute Transformation，它不是访问器（Accessor）
Attribute Transformation 指的是在模型序列化为数组或 JSON 时，对属性值进行统一格式转换的行为。它和 getFooAttribute 这类访问器不同：访问器影响读取时的值，而 Transformation 只作用于 toArray() 和 toJson() 等导出操作，不改变模型内部存储或数据库交互逻辑。
常见误用是把日期格式化、金额补零、布尔转字符串等逻辑全塞进访问器里，结果导致模型在查询构造、条件判断、关系加载时也触发这些转换，引发意外类型错误或性能损耗。
- Transformation 是“只出不入”的单向处理，仅在序列化阶段生效
- 它不参与模型填充（
fill()）、批量赋值（create()）或 SQL 构建 - 底层由
serializeDate()和asJson()协同控制，但最常用、最可控的方式是重写toArray()
如何安全覆盖 toArray() 实现通用转换
直接重写 toArray() 是 Laravel 中最稳定、最易调试的通用转换入口。它天然兼容所有嵌套关系（with() 加载的关联也会走各自模型的 toArray()），且不会干扰 Eloquent 的生命周期钩子。
注意：不要在 toArray() 里调用 parent::toArray() 后再遍历修改 —— 这会丢失关系数据的递归处理逻辑；正确做法是先调用父方法拿到完整结构，再对顶层字段做针对性替换。
立即学习“PHP免费学习笔记（深入）”；
- 日期字段统一转为 ISO8601 字符串：
$data['created_at'] = $this->created_at?->format('c'); - 金额字段保留两位小数并转字符串（避免 JS 浮点误差）：
$data['price'] = number_format($this->price, 2, '.', ''); - 空字符串或 null 布尔字段转为 false：
$data['is_active'] = (bool) $this->is_active; - 敏感字段（如
password_hash）应在此处 unset，而不是靠隐藏字段（$hidden），因为后者不作用于手动调用toArray()的场景
casts 和 serializeDate() 的适用边界在哪
casts 适用于模型属性的“运行时类型保障”，比如把数据库里的 JSON 字符串自动转成 PHP 数组，或把整数自动转为 Carbon 实例。但它无法控制输出格式 —— cast 为 'date' 的字段，在 toArray() 中仍按 Carbon 默认格式（Y-m-d）输出，不能改成 Y/m/d 或时间戳。
serializeDate() 仅影响日期类 cast（date、datetime、immutable_date 等）的序列化格式，且全局生效。如果你有多个模型需要不同日期格式（如日志用时间戳、前端展示用中文格式），硬编码在基类里反而造成耦合。
- 用
casts处理「输入→内存」转换（如 JSON → array，int → bool） - 用
serializeDate()统一管理「内存→输出」的日期格式，仅当所有日期字段格式一致时才推荐 - 混合场景（部分日期要时间戳、部分要带时区字符串）必须退回到
toArray()手动控制
关联模型的转换容易漏掉什么
很多人只改了主模型的 toArray()，却忘了关联模型（如 User::with('posts')）是否也做了同样处理。结果主模型日期格式正常，posts 里的 published_at 还是默认 Y-m-d。
更隐蔽的问题是：如果关联模型用了 $appends 添加了计算属性（如 is_published），而该属性依赖未转换的原始字段（如直接读 $this->published_at > now()），那么即使主模型日期已转字符串，关联模型内部仍用 Carbon 实例比对 —— 这本身没问题，但一旦你在主模型的 toArray() 里提前把 $this->posts 调成了数组再处理，就可能破坏对象链，导致 is_published 计算失效。
- 确保所有被
with()加载的模型类都实现了自己的toArray() - 避免在主模型中用
$this->posts->toArray()强制扁平化，应让 Eloquent 自动调用各模型的toArray() - 若需对关联字段二次加工（如给每篇 post 加一个
read_time_minutes），应在对应关联模型中定义访问器 +$appends，而不是在主模型里循环处理
真正难的不是写转换逻辑，而是判断哪一层该做什么事：数据库层管存储精度，模型属性层管运行时类型，序列化层管对外契约。混用这三层，早晚会在某个导出接口里发现时间少了 8 小时，或金额变成 99.99999999999999。
