序列化-Laravel 文档-果果开发

简介

在使用 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 对象。当 Eloquent 模型和集合从路由或控制器中返回时，Laravel 会自动将其序列化为 JSON：

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

关系

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

从 JSON 中隐藏属性

有时你可能希望限制模型的数组或 JSON 表示中包含的属性，例如密码。为此，你可以在模型上使用 Hidden 特性。列在 Hidden 特性中的属性不会包含在模型的序列化表示中：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}

若要隐藏关系，请将关系的方法名添加到 Eloquent 模型的 Hidden 特性中。

或者，你可以使用 Visible 特性来定义一个“允许列表”，列出应包含在模型数组和 JSON 表示中的属性。未出现在 Visible 特性中的属性，在模型转换为数组或 JSON 时会被隐藏：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}

临时修改属性可见性

如果你希望在给定模型实例上让一些通常隐藏的属性可见，可以使用 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 时，你可能希望添加数据库中没有对应列的属性。为此，首先要为该值定义一个访问器：

<?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 特性。请注意，属性名通常以其“蛇形命名法”的序列化形式引用，尽管访问器的 PHP 方法是使用“驼峰命名法”定义的：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}

一旦该属性被添加到 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();

同样，如果你希望从模型中移除所有追加属性，可以使用 withoutAppends 方法：

return $user->withoutAppends()->toArray();

日期序列化

自定义默认日期格式

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

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

按属性自定义日期格式

你可以通过在模型的类型转换声明中指定日期格式，来自定义单个 Eloquent 日期属性的序列化格式：

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