Laravel模型日期序列化？日期序列化如何自定义？-Laravel-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

登录后复制

属性：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    /**
     * The storage format of the model's date columns.
     *
     * @var string
     */
    protected $dateFormat = 'Y-m-d H:i:s'; // 这个Post模型的所有日期字段都会用这个格式

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

登录后复制

这个

$dateFormat

登录后复制

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

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

$casts

登录后复制

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

datetime

登录后复制

类型，并指定一个格式：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Event extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'start_date' => '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时生效，提供了极高的灵活性。

DeepBrain

AI视频生成工具，ChatGPT +生成式视频AI =你可以制作伟大的视频!

查看详情

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

登录后复制

-youjiankuohaophpcn

$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
```
登录后复制
实例再处理。