Laravel模型日期序列化？日期序列化如何自定义？

煙雲

发布时间：2025-09-05 09:27:01

840人浏览过

来源于php中文网

原创

Laravel默认将模型日期序列化为ISO 8601格式，可通过全局Carbon::serializeUsing、模型$dateFormat或字段级$casts灵活自定义，推荐使用$casts实现精细控制且不影响存储。

laravel模型日期序列化？日期序列化如何自定义？

Laravel模型日期序列化，简单来说，就是当你把一个模型实例转换成数组或JSON格式输出时（比如通过API接口返回数据），模型里的日期字段（例如

created_at

updated_at

）会以什么形式呈现。默认情况下，Laravel会把这些日期字段处理成

Carbon

实例，然后在序列化时自动转换为标准的ISO 8601格式字符串。至于如何自定义，嗯，这正是Laravel的魅力所在，它提供了多种灵活的途径，从全局设置到模型内部的精细控制，甚至到单个字段的特定格式，都可以随心所欲地调整。

解决方案

Laravel在日期序列化这块，默认做得挺好的，它会把

created_at

、

updated_at

以及你在

$dates

属性里定义的字段自动转换为

Carbon

实例，然后序列化时输出ISO 8601格式。但如果你想“改头换面”，有几种主流且优雅的方式：

1. 全局日期格式化： 如果你希望整个应用中所有模型的日期字段都遵循同一个自定义格式，可以在

AppServiceProvider

的

boot

方法中设置

Carbon

的序列化行为：

use Carbon\Carbon;
use Illuminate\Support\Facades\Schema; // 如果需要，可以引入

public function boot()
{
    // ... 其他 boot 方法内容

    Carbon::serializeUsing(function ($carbon) {
        return $carbon->format('Y-m-d H:i:s'); // 比如，我们都想要这种格式
    });

    // 或者，如果你只关心 JSON 序列化，且使用 Laravel 9+
    // Json::encodeUsing(function ($value) {
    //     if ($value instanceof Carbon) {
    //         return $value->format('Y-m-d H:i:s');
    //     }
    //     return null; // 或者其他默认处理
    // });
}

这种方式很“霸道”，一旦设置，全局生效。这意味着所有通过

toArray()

或

toJson()

方法输出的日期都会变成这个格式。

2. 模型级别日期格式化： 如果你只想针对某个特定模型改变日期格式，可以在模型中定义

$dateFormat

属性：

这个

$dateFormat

不仅影响序列化输出，还会影响日期字段存入数据库时的格式。所以，如果你只是想改变输出格式，而不改变存储格式，就要小心使用了。

3. 字段级别日期格式化（推荐）： 这是我个人最喜欢也最推荐的方式，因为它足够精细，可以针对模型中的每一个日期字段设置不同的格式，而且不会影响数据库存储格式。通过

$casts

属性，你可以把日期字段转换为

datetime

类型，并指定一个格式：

 'datetime:Y-m-d H:i', // 精确到分钟
        'end_date' => 'datetime:Y-m-d H:i:s', // 精确到秒
        'published_at' => 'date:Y-m-d', // 只显示日期
    ];

    // ... 其他模型属性和方法
}

这种方式的强大之处在于，它只影响序列化输出和从数据库读取时的类型转换，不会干预数据库实际存储的格式（数据库通常还是存储

datetime

或

TIMESTAMP

类型）。当你从数据库取出数据时，

start_date

字段会自动变成

Carbon

实例，并且在序列化时，会按照

Y-m-d H:i

的格式输出。

Laravel日期序列化默认行为是怎样的，以及我该如何理解它？

说实话，刚接触Laravel的时候，我有时也会纳闷，为什么我的

created_at

字段在API响应里长得那么“奇怪”，比如

2023-10-27T10:30:00.000000Z

这种。这就是Laravel的默认行为，它遵循的是 ISO 8601 标准。

ISO 8601 格式其实是个非常棒的选择，尤其对于API和跨系统通信来说。它具有明确的结构，包含了日期、时间，甚至毫秒级精度和时区信息（那个

就代表UTC时间）。机器处理起来非常友好，不容易出错。Laravel之所以选择它，就是为了提供一个普适、国际化且无歧义的日期表示方式。

具体来说，Laravel模型会将

created_at

、

updated_at

、

deleted_at

（如果你使用了软删除）以及你在模型中

$dates

属性里定义的任何字段自动转换为

Carbon

实例。

Carbon

是PHP的一个日期时间处理库，它极大地简化了日期操作。当模型被序列化成数组或JSON时，这些

Carbon

实例就会被自动调用其

jsonSerialize()

方法，默认输出ISO 8601格式的字符串。

所以，当你看到

2023-10-27T10:30:00.000000Z

时，别慌，这并非错误，而是Laravel为了数据传输的标准化和健壮性所做的默认处理。它告诉我们，这个时间是UTC时间，精确到微秒。如果你在前端接收到这个格式，通常会用JavaScript的

Date

对象或者专门的日期库（比如

moment.js

或

date-fns

）来解析和格式化，以适应用户的本地显示习惯。理解这一点，能帮助我们更好地设计前后端交互，避免不必要的格式转换问题。

我如何为特定模型或特定字段，甚至全局地，自定义日期输出格式？

要自定义日期输出格式，我们手头有几个工具，选择哪个取决于你的具体需求和“影响范围”。我通常会从最细粒度的控制开始考虑，如果不行再往上走。

1. 字段级别的精细控制（首选）： 如前所述，

$casts

属性是我的首选。它允许你为模型中的每个日期字段单独指定格式，互不干扰。

class Product extends Model
{
    protected $casts = [
        'available_from' => 'datetime:Y-m-d', // 仅日期
        'promotion_ends_at' => 'datetime:Y-m-d H:i', // 日期和时间（分钟）
        'last_updated_by_admin' => 'datetime:Y-m-d H:i:s P', // 包含时区偏移
    ];
}

这种方式的好处在于，它不会影响数据库存储，也不会影响其他模型的日期格式。它只在模型被转换成数组或JSON时生效，提供了极高的灵活性。

bloop

快速查找代码，基于GPT-4的语义代码搜索

下载

2. 模型级别的统一格式： 如果你发现一个模型里所有日期字段都需要统一的格式，那么

$dateFormat

属性就派上用场了。

class Order extends Model
{
    protected $dateFormat = 'Y-m-d H:i:s'; // 订单模型的所有日期都用这个格式
}

这个设置会覆盖全局的

Carbon::serializeUsing()

，但它有个“副作用”：它也会影响模型保存日期到数据库时的格式。如果你数据库的日期字段类型是

datetime

或

TIMESTAMP

，通常可以兼容

Y-m-d H:i:s

，但如果你有其他自定义的日期类型或格式要求，就要留意了。我个人在用

$dateFormat

时会比较谨慎，通常只在确认不会影响数据库存储时才用。

3. 全局统一格式（慎用）： 当你真的、真的希望整个应用的所有日期输出都保持一个固定格式时，才考虑在

AppServiceProvider

中使用

Carbon::serializeUsing()

。

// AppServiceProvider.php
public function boot()
{
    Carbon::serializeUsing(function ($carbon) {
        return $carbon->format('Y-m-d H:i:s');
    });
}

这个方法是最“粗暴”的，它会影响所有

Carbon

实例的序列化行为，包括模型之外的

Carbon

对象。虽然方便，但可能会导致一些意想不到的副作用，比如某些第三方库或内部逻辑可能依赖

Carbon

默认的ISO 8601格式。所以，在使用全局设置时，最好确保你的应用对日期格式有高度一致性的要求，并且仔细测试。

总的来说，从精细到粗略，

$casts

$dateFormat

Carbon::serializeUsing()

是一个逐步放宽控制的路径。我通常会优先考虑

$casts

，因为它提供了最佳的平衡点：足够灵活，且对其他部分的影响最小。

在处理日期序列化时，有哪些容易踩的坑和有效的调试方法？

处理日期序列化，看似简单，实则暗藏玄机。我踩过的坑，多多少少都跟对时间、时区、以及Laravel内部机制理解不够透彻有关。

1. 时区混乱： 这是最常见的“坑”。Laravel默认将所有日期存储为UTC时间，并在从数据库读取时，根据

config/app.php

中的

timezone

设置将其转换为应用的时区。但序列化时，如果使用ISO 8601，它会带上

表示UTC。如果你在前端直接显示这个UTC时间，而用户在不同时区，就会出现时间不匹配的问题。

调试方法：

dd($model->created_at)
: 在序列化之前，直接
```
dd
```
模型的日期字段。你会看到一个
```
Carbon
```
实例，其中包含了
```
Date
```
(实际时间字符串) 和
```
timezone
```
(通常是
```
UTC
```
或你的应用时区)。
dd($model->toArray())
或
dd($model->toJson())
: 查看最终序列化后的输出，确认日期字符串是否符合预期。
配置检查: 确认
```
config/app.php
```
中的
```
timezone
```
设置是否正确。通常建议将其设置为
```
UTC
```
，然后在前端进行时区转换，或者在需要时，在后端进行明确的时区转换再输出。

$dates

属性遗漏或误用： 如果你有一个自定义的日期字段（比如

published_at

），但忘记把它添加到模型的

$dates

属性中，或者没有在

$casts

中明确指定其类型，那么这个字段在序列化时就不会被转换为

Carbon

实例，而是以原始的字符串形式输出。这意味着你无法对其进行

Carbon

方法操作，也无法享受自动格式化。

调试方法：

检查模型属性: 确保

protected $dates = ['published_at'];

或者

protected $casts = ['published_at' => 'datetime'];

存在且正确。

类型检查:
```
dd(gettype($model->published_at))
```
，如果不是
```
object
```
且
```
Carbon\Carbon
```
，那肯定哪里出了问题。

$dateFormat

的双重影响： 前面提过，

$dateFormat

不仅影响序列化输出，还影响日期存入数据库时的格式。如果你不小心把它设置成了一个数据库不支持的格式，或者与数据库期望的格式不符，可能会导致数据存储失败或格式错误。

调试方法：

数据库日志: 开启数据库查询日志，查看
```
INSERT
```
或
```
UPDATE
```
语句中日期字段的实际格式。
测试写入: 简单地创建一个模型实例并保存，然后检查数据库中的日期字段是否正确存储。

4. 覆盖

toArray()

或
jsonSerialize()
带来的副作用：有些时候，为了实现非常复杂的序列化逻辑，你可能会选择直接覆盖模型的

toArray()

或

jsonSerialize()

方法。这固然强大，但也容易“破坏”Laravel默认的日期处理机制，导致日期字段不再自动转换为

Carbon

实例或按预期格式化。

调试方法：

逐步回溯: 如果你覆盖了这些方法，尝试注释掉你的自定义逻辑，看看默认行为是否正常。
手动处理: 在自定义的
```
toArray()
```
或
```
jsonSerialize()
```
中，确保你手动调用了日期字段的
```
format()
```
方法，或者明确地将其转换为
```
Carbon
```
实例再处理。

5. 前后端格式不一致的预期： 这算不上Laravel的坑，更多是前后端协作的坑。后端可能默认输出ISO 8601，而前端期望的是