序列化

介绍

在使用 Laravel 构建 API 时，你通常需要将模型及其关联关系转换为数组或 JSON。Eloquent 提供了便捷的方法来实现这些转换，同时还能控制在模型序列化表示中包含哪些属性。

如果你希望更强大地处理 Eloquent 模型和集合的 JSON 序列化，可以查看关于 Eloquent API 资源的文档。

模型与集合的序列化

序列化为数组

要将模型及其已加载的关联关系转换为数组，可以使用 toArray 方法。该方法是递归的，因此模型的所有属性以及所有关联关系（包括关联关系的关联关系）都会被转换为数组：

use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();

如果你只想将模型的属性转换为数组，而不包括关联关系，可以使用 attributesToArray 方法：

$user = User::first();

return $user->attributesToArray();

你也可以通过在集合实例上调用 toArray 方法，将整个模型集合转换为数组：

$users = User::all();

return $users->toArray();

序列化为 JSON

要将模型转换为 JSON，可以使用 toJson 方法。与 toArray 方法类似，toJson 方法是递归的，因此模型的所有属性及关联关系都会被转换为 JSON。你还可以指定 PHP 支持的任何 JSON 编码选项：

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

或者，你也可以将模型或集合强制转换为字符串，这会自动调用模型或集合的 toJson 方法：

return (string) User::find(1);

由于模型和集合在被转换为字符串时会自动转换为 JSON，因此你可以直接从应用的路由或控制器返回 Eloquent 对象。Laravel 会在路由或控制器返回时自动将 Eloquent 模型和集合序列化为 JSON：

Route::get('/users', function () {
    return User::all();
});

关联关系

当 Eloquent 模型被转换为 JSON 时，其已加载的关联关系会自动作为属性包含在 JSON 对象中。此外，尽管 Eloquent 的关联关系方法使用驼峰命名（camelCase）定义，但关联关系在 JSON 中的属性名会自动转换为蛇形命名（snake_case）。

从 JSON 隐藏属性

有时你可能希望限制模型在转换为数组或 JSON 时包含的属性，例如密码。为此，可以在模型中添加 $hidden 属性。列在 $hidden 数组中的属性在模型序列化时将不会被包含：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 序列化时应隐藏的属性。
     *
     * @var array<string>
     */
    protected $hidden = ['password'];
}

要隐藏关联关系，只需将关联关系的方法名添加到模型的 $hidden 属性中即可。

或者，你也可以使用 $visible 属性定义一个“允许列表”，指定模型数组或 JSON 表示中应该包含的属性。所有未列在 $visible 数组中的属性在转换为数组或 JSON 时都会被隐藏：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 在数组中应可见的属性。
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

临时修改属性可见性

如果你希望在某个模型实例上临时显示通常被隐藏的属性，可以使用 makeVisible 或 mergeVisible 方法。makeVisible 方法会返回模型实例：

return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();

同样地，如果你希望临时隐藏某些通常可见的属性，可以使用 makeHidden 或 mergeHidden 方法：

return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();

如果你希望临时覆盖所有可见或隐藏属性，可以分别使用 setVisible 和 setHidden 方法：

return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();

向 JSON 添加附加值

有时在将模型转换为数组或 JSON 时，你可能希望添加一些在数据库中没有对应列的属性。为此，首先需要为该属性定义一个访问器（Accessor）：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 判断用户是否为管理员。
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

如果你希望该访问器始终被添加到模型的数组和 JSON 表示中，可以将属性名加入模型的 $appends 属性。注意，属性名通常使用序列化后的“蛇形命名”（snake_case）表示，即使访问器在 PHP 中是以驼峰命名（camelCase）定义的：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 要附加到模型数组形式的访问器属性。
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

一旦将属性添加到 $appends 列表，它将包含在模型的数组和 JSON 表示中。同时，$appends 中的属性也会遵循模型上配置的 $visible 和 $hidden 设置。

运行时附加属性

在运行时，你可以使用 append 或 mergeAppends 方法指示模型实例附加额外的属性；或者使用 setAppends 方法覆盖该模型实例的附加属性数组：

return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();

日期序列化

自定义默认日期格式

你可以通过重写 serializeDate 方法来自定义模型序列化时的默认日期格式。该方法只影响数组或 JSON 序列化时的日期格式，不会改变日期在数据库中的存储格式：

/**
 * 准备日期用于数组或 JSON 序列化。
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

为单个属性自定义日期格式

你也可以通过在模型的类型转换（casts）中指定日期格式，为单个 Eloquent 日期属性自定义序列化格式：

protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}

api资源

Eloquent工厂