PHP处理Eloquent属性格式技巧

本文深入解析了 Laravel Eloquent 中属性格式化的最佳实践，明确指出 `$casts` 是处理日期、布尔值和数字等基础类型自动转换的首选方案——它在模型生命周期内全局、静默、可靠地完成类型转换，保障 `where()` 查询、API 响应和序列化行为的一致性；而访问器仅适用于展示层定制化格式（如手机号脱敏、时间差显示），需配合 `$appends` 才能进入数组输出；文章还揭露了常见陷阱：误用 `'Carbon'` 作为 cast 类型导致静默失败、`$casts` 对 `null` 的强制转换可能破坏业务逻辑、以及 `getAttributes()` 与 `toArray()` 在格式化行为上的关键差异，帮助开发者避开低级却致命的坑。

为什么 $casts 比访问器更适合日期/布尔/数字格式化

因为 $casts 在模型从数据库读取后、写入前自动完成类型转换，不依赖手动调用，且对 JSON 序列化、API 响应、toArray() 全局生效。访问器（getFooAttribute）只在读取属性时触发，且不会影响 where() 查询或批量赋值。

常见错误：用访问器处理日期格式（如 Carbon::parse($this->attributes['created_at'])->format('Y-m-d')），结果导致 created_at 在 whereDate('created_at', '2024-01-01') 中失效——数据库字段仍是原始字符串，而模型里存的是格式化后的字符串。

• $casts = ['is_active' => 'boolean']：把 tinyint(1) 或 '1' 自动转为 true，比手写 boolval() 更可靠
• $casts = ['price' => 'decimal:2']：确保小数点后两位，但注意这仅影响 PHP 层类型，不改变数据库精度
• $casts = ['metadata' => 'array']：自动 json_encode/json_decode，避免手动处理 JSON 字段出错

日期字段必须用 date 或 datetime cast，别信 Carbon 类型名

Laravel 的 $casts 不接受 'created_at' => 'Carbon' 这种写法——会静默失败，字段仍为字符串。正确方式只有 'date'（只保留年月日）、'datetime'（含时分秒）、'immutable_date' 等内置类型。

使用场景：需要在 Blade 中直接输出 {{ $post->published_at->diffForHumans() }}，前提是它已是 Carbon 实例。若 cast 错误，调用 diffForHumans() 会报 Call to a member function diffForHumans() on string。

• ✅ 正确：$casts = ['published_at' => 'datetime'] → 得到 Carbon 实例
• ❌ 错误：$casts = ['published_at' => 'Carbon'] 或 $casts = ['published_at' => 'string']
• ⚠️ 注意：'date' 会截断时间部分，whereTime() 将无法匹配小时分钟

自定义格式（如手机号脱敏、金额千分位）该用访问器还是 Mutator

这类展示层格式化不该进 $casts，因为它们破坏数据原始性，且无法反向解析。例如把 13812345678 转成 138****5678 后，就再也无法用于发送短信了。

应该用访问器（getPhoneAttribute）提供只读格式化字段，并保留原始字段可写。同时配合 $appends 让它出现在 toArray() 中。

• 定义：protected $appends = ['phone_formatted'];
• 访问器：public function getPhoneFormattedAttribute() { return substr($this->phone, 0, 3) . '****' . substr($this->phone, -4); }
• Mutator（如需写入脱敏值）要格外小心：除非业务明确要求存储脱敏数据，否则不要重写 setPhoneAttribute
• 性能提示：访问器每次读取都执行，高频列表页建议用 SELECT CONCAT(LEFT(phone,3), '****', RIGHT(phone,4)) as phone_formatted 在查询层处理

getAttributes() 和 toArray() 对格式化字段的行为差异

getAttributes() 返回原始数据库值（绕过所有访问器和 cast），toArray() 则应用了 $casts 和访问器（包括 $appends 字段）。调试时混淆这两者，常导致“明明写了访问器却没生效”的困惑。

典型问题：API 接口返回数据中 price_formatted 是空的，但 dd($model->price_formatted) 又能打印出来——大概率是忘了加 $appends，或者用了 getAttributes() 而非 toArray()。

• $model->getAttributes()['price'] → 原始数据库值（如 9999.99 或 '9999.99'）
• $model->toArray()['price'] → 经 $casts 转换后的值（如 9999.99 float）
• $model->toArray()['price_formatted'] → 仅当 price_formatted 在 $appends 中才存在

最易被忽略的一点：$casts 对 null 值也强制转换，比如 'status' => 'integer' 遇到数据库 NULL，会变成 0 而非 null，可能掩盖空值逻辑。需要保持 null 语义时，得用访问器手动判断。

到这里，我们也就讲完了《PHP处理Eloquent属性格式技巧》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！