Eloquent Attribute Expansion 是开发者对“将 JSON 或多个扁平字段自动映射为嵌套对象/数组属性”的俗称。Laravel 无原生支持，需通过 cast（如 'meta' => 'array'）、访问器（get*Attribute）或重写 toArray() 实现，注意 $appends、$hidden 配置及 cast 与访问器行为差异。
什么是 Eloquent Attribute Expansion？
这不是 Laravel 官方术语，而是开发者对「把数据库里一个 JSON 字段或多个扁平字段，自动映射成嵌套对象/数组属性」的通俗叫法。Laravel 本身不提供开箱即用的“属性展开”机制，但可通过 get* 访问器 + cast + toArray() 配合手动处理实现。关键在于：你得明确告诉 Eloquent 哪些字段要“拆开”，以及怎么拆。
用 cast + array/object 类型实现 JSON 字段自动展开
最常见场景是数据库里有个 meta 字段存 JSON，你想访问 $model->meta->color 或 $model->meta['size']。这时候别手写 getMetaAttribute，直接用 cast 更安全、更一致：
- 在模型中声明
protected $casts = ['meta' => 'array'];，读取时自动json_decode($value, true) - 若想获得对象而非数组，用
'meta' => 'object'，之后可写$model->meta->color - 注意：
objectcast 返回的是stdClass，不是你自定义的类；如需强类型，得配合getAttribute或访问器 - 写入时，Eloquent 会自动
json_encode，但只对顶层字段生效；嵌套结构修改后需重新赋值，例如：$model->meta = array_merge($model->meta, ['updated_at' => now()]);
从多个字段拼出嵌套结构：用访问器（Accessors）
当数据分散在 shipping_address_line1、shipping_address_line2、shipping_city 等字段，又不想改表结构时，访问器是最直接的展开方式：
public function getShippingAddressAttribute()
{
return [
'line1' => $this->shipping_address_line1,
'line2' => $this->shipping_address_line2,
'city' => $this->shipping_city,
'zip' => $this->shipping_zip,
];
}
这样调用 $model->shipping_address['city'] 就能拿到值。但要注意：
立即学习“PHP免费学习笔记（深入）”；
- 该属性默认不会出现在
toArray()或 API 响应里，需在$appends中显式添加：protected $appends = ['shipping_address']; - 访问器返回数组，无法链式调用
->city；如需对象风格，返回new \stdClass或用json_decode(json_encode(...), false) - 不要在访问器里做 heavy 查询或 I/O，它会在每次访问时触发
toArray() 时动态嵌套：重写 toArray() 或用 makeHidden/makeVisible
有时你希望 API 输出时自动把 user_name、user_email 合并进 user 对象，但模型本身不存 user 字段。这时不能只靠访问器，得干预序列化流程：
- 重写
toArray()是最彻底的方式，但破坏了 Eloquent 默认行为，后续扩展难维护 - 更轻量的做法是：先定义好访问器（如
getUserAttribute），再在控制器中手动构造：['user' => $model->user] - 若已用
$appends加入嵌套属性，记得检查$hidden是否意外屏蔽了底层字段（比如user_name被隐藏后，访问器可能拿不到原始值） - Laravel 10+ 支持
transform方法，可在集合层面统一处理，比单个模型toArray更适合列表场景
真正容易被忽略的是：JSON 字段的 cast 和访问器混用时，getAttribute('meta') 返回的是 cast 后的结果，而 $this->meta 可能触发访问器——两者行为不一致，调试时容易绕晕。
