Laravel模型日期格式？日期如何格式化？

陆砚码

2026-10-28 • 👁 0人浏览过

Laravel模型通过Carbon库自动处理created_at和updated_at为Carbon实例，自定义日期字段需用$casts属性转换，结合serializeDate方法可统一API输出格式，并推荐数据库存储UTC时间、显示时按需转换时区，同时支持$dates、访问器和修改器等扩展方式。 Laravel 模型处理日期，核心就是利用

Carbon

库。默认情况下，

created_at

和

updated_at

字段会自动转换为

Carbon

实例，方便我们进行各种操作。对于其他自定义日期字段，我们需要通过模型的

$casts

属性明确告诉 Laravel 它们是日期类型。至于格式化，那就完全是

Carbon

的舞台了，它提供了极其丰富的格式化方法，能满足你几乎所有的需求。说实话，Laravel 在日期处理上做得相当贴心，省去了我们很多麻烦。当你从数据库中取出一条记录时，那些被 Laravel 识别为日期的字段（比如

created_at

updated_at

，甚至是你在

$casts

中定义的

date

或

datetime

类型），都会被自动包装成

Carbon

实例。这意味着你拿到的不是一个简单的字符串，而是一个功能强大的日期对象。比如，你有一个

Post

模型，里面有个

published_at

字段：

class Post extends Model
{
    protected $casts = [
        'published_at' => 'datetime', // 告诉 Laravel 这是一个日期时间字段
    ];

    // ...
}

当你获取一个

Post

实例后，你可以直接这样操作

published_at

：

$post = App\Models\Post::find(1);

// 访问 Carbon 实例
echo $post->published_at; // 默认输出 Y-m-d H:i:s 格式

// 格式化输出
echo $post->published_at->format('Y年m月d日 H:i'); // 2023年10月27日 14:30

// 计算时间差
echo $post->published_at->diffForHumans(); // 1小时前

// 修改日期
$post->published_at = now(); // 直接赋值 Carbon 实例或日期字符串
$post->save();

这个

casts

属性是真的好用，它让模型和数据库之间的类型转换变得透明而高效。 Laravel 模型默认日期字段是如何工作的？嗯，说到 Laravel 模型里的日期，

created_at

和

updated_at

这两个字段真是“老熟人”了。它们是 Laravel 约定俗成的时间戳字段，当你创建或更新一个模型时，Laravel 会自动帮你填充它们。更妙的是，框架不仅仅是把它们存成数据库里的时间戳或者字符串，当数据从数据库取出来时，它们会被自动转换成

Carbon

实例。

Carbon

是一个继承自 PHP

DateTime

类的库，但它提供了超级多的便捷方法来处理日期和时间。在我看来，这简直是 PHP 日期处理的瑞士军刀。这意味着你拿到

$model->created_at

时，可以直接调用各种

Carbon

方法，比如

->format('Y-m-d')

来格式化，

->addDay()

来增加一天，或者

->isToday()

来判断是不是今天。这种开箱即用的便利性，大大减少了我们写样板代码的时间。如何自定义 Laravel 模型中的日期字段格式？除了默认的

created_at

和

updated_at

，我们自己的业务字段也经常需要存日期，比如订单的

delivery_date

，或者文章的

publish_time

。这时候，

$casts

属性就派上大用场了。我个人觉得，这是处理自定义日期字段最优雅的方式。在模型里定义

$casts

数组，把你的日期字段名映射到

'date'

、

'datetime'

或者

'timestamp'

类型。

class Order extends Model
{
    protected $casts = [
        'delivery_date' => 'date',      // 只关心日期部分，时间会被忽略
        'expected_delivery_time' => 'datetime', // 日期和时间都关心
        'processed_at' => 'timestamp',  // 存储为 Unix 时间戳
    ];
}

一旦这样设置，当你访问

$order->delivery_date

时，Laravel 就会自动给你一个

Carbon

实例。然后，你就可以用

Carbon

提供的

format()

方法随心所欲地格式化输出了。

$order = Order::find(1);
echo $order->delivery_date->format('Y年m月d日'); // 输出 '2023年10月27日'
echo $order->expected_delivery_time->format('H:i'); // 输出 '14:30'

这种做法比以前通过 Accessor (访问器) 来手动转换要简洁和高效得多，也更符合“约定优于配置”的原则。当通过 API 返回数据时，如何统一 Laravel 模型日期字段的输出格式？这真的是一个非常实际的需求，尤其是在前后端分离的项目中。前端通常希望收到统一的日期格式，比如 ISO 8601 格式（

YYYY-MM-DDTHH:mm:ss.sssZ

）或者其他特定的格式。如果每个日期字段都手动

format()

一遍，那工作量可就大了，而且容易出错。 Laravel 给了我们一个很棒的解决方案：在模型中重写

serializeDate

方法。这个方法会在模型被序列化为数组或 JSON 时被调用，让你有机会统一处理所有日期字段的输出格式。 PHP 8.5.5 PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。下载

use DateTimeInterface;

class User extends Model
{
    // ...

    /**
     * Prepare a date for array / JSON serialization.
     */
    protected function serializeDate(DateTimeInterface $date): string
    {
        // 我通常喜欢用 ISO 8601 格式，对前端很友好
        return $date->format('Y-m-d H:i:s');
        // 或者更标准的 ISO 8601，带时区信息
        // return $date->toIso8601String();
    }
}

你看，只要定义了

serializeDate

，所有被 Laravel 识别为

Carbon

实例的日期字段（包括

created_at

updated_at

以及

$casts

中定义的日期字段），在调用

$user->toArray()

或

json_encode($user)

时，都会按照你指定的方式进行格式化。这极大地简化了 API 接口的日期输出管理，保持了数据的一致性。处理时区问题在 Laravel 日期格式化中需要注意什么？时区，这玩意儿在跨区域应用里真是个老大难问题。我见过不少项目因为时区处理不当，导致数据混乱或者显示错误。在 Laravel 中，时区配置主要在

config/app.php

文件的

timezone

选项里。默认通常是

UTC

，这在我看来是个非常明智的选择。我的建议是：数据库存储统一使用 UTC 时间。这是最佳实践。这样无论你的服务器部署在哪里，或者用户来自哪个时区，数据库里的时间都是一个统一的基准。Laravel 默认在保存日期到数据库时，会根据

app.php

中的

timezone

配置进行转换。显示时，再根据用户或应用的需要进行时区转换。当你从数据库取出

Carbon

实例后，可以利用

Carbon

的

setTimezone()

方法来转换到目标时区。

// config/app.php
'timezone' => 'UTC', // 确保你的应用时区是 UTC

$post = App\Models\Post::find(1);

// 假设数据库里存的是 UTC 时间 2023-10-27 10:00:00
// 如果你的应用时区是 UTC，那 $post->created_at 也是 UTC
echo $post->created_at->format('Y-m-d H:i:s'); // 2023-10-27 10:00:00 (UTC)

// 如果要显示给北京用户（东八区）
echo $post->created_at->setTimezone('Asia/Shanghai')->format('Y-m-d H:i:s');
// 应该会输出 2023-10-27 18:00:00 (北京时间)

// 或者更简洁地直接转换并格式化
echo $post->created_at->tz('Asia/Shanghai')->format('Y-m-d H:i:s');

这样，数据的存储和显示逻辑就清晰分开了，大大降低了时区带来的复杂性。千万别小看时区问题，它能让你的用户体验瞬间崩塌。在 Laravel 模型中，除了

casts

还有哪些方式可以处理日期？虽然

casts

是我最推荐的日期处理方式，但 Laravel 提供了不止一种方法来处理模型日期，了解它们的不同应用场景也挺有意思的。

$dates

属性 (传统方式): 在

$casts

出现之前，我们通常会在模型中定义一个

$dates

数组，列出所有需要被转换为

Carbon

实例的日期字段。

class Product extends Model
{
    protected $dates = [
        'expires_at',
        'created_at',
        'updated_at',
    ];
}

它和

$casts

都能让字段变成

Carbon

实例，但

$casts

更灵活，可以指定更具体的类型（如

date

或

datetime

），而且能处理更多非日期类型。所以，现在一般推荐使用

$casts

。 Accessors (访问器) 和 Mutators (修改器): 这是一种更通用的模型属性处理机制。如果你需要对日期进行一些复杂的处理，而不仅仅是简单的类型转换，访问器和修改器就很有用了。访问器 (Accessor): 在获取属性时对它进行处理。

class Article extends Model
{
    public function getPublishedAtAttribute($value)
    {
        // 假设数据库里存的是 Unix 时间戳，或者其他非标准格式
        return Carbon::parse($value)->format('Y年m月d日');
    }
}

这样，当你访问

$article->published_at

时，它会返回一个格式化好的字符串。不过，这种方式返回的是字符串，如果你还需要对日期进行

Carbon

操作，就得再次

Carbon::parse()

，略显麻烦。修改器 (Mutator): 在设置属性时对它进行处理。

class Event extends Model
{
    public function setEventDateAttribute($value)
    {
        // 在保存到数据库之前，确保它是一个标准格式
        $this->attributes['event_date'] = Carbon::parse($value)->toDateString();
    }
}

当

$event->event_date = '明天'

时，修改器会尝试解析并将其转换为

Y-m-d

格式存储。在我看来，对于简单的日期类型转换，

$casts

是首选，它更自动化、更简洁。但如果你的日期字段需要进行复杂的计算、条件判断，或者在存取时有特殊的业务逻辑，那么访问器和修改器就是更灵活的工具。它们各有侧重，配合使用能让你的模型更加健壮。

相关文章