Eloquent：序列化

• 简介
• 序列化模型和集合
  • 序列化为数组
  • 序列化为 JSON
• 从 JSON 中隐藏属性
• 将值附加到 JSON
• 日期序列化

简介

在使用 Laravel 构建 API 时，您通常需要将模型和关系转换为数组或 JSON。Eloquent 包含用于进行这些转换的便捷方法，以及控制哪些属性包含在模型的序列化表示中的方法。

序列化模型和集合

序列化为数组

要将模型及其加载的 关系转换为数组，您应该使用 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 关系方法是使用“驼峰式”方法名称定义的，但关系的 JSON 属性将是“蛇形命名法”。

从 JSON 中隐藏属性

有时，您可能希望限制包含在模型的数组或 JSON 表示中的属性，例如密码。为此，请在您的模型中添加 $hidden 属性。$hidden 属性的数组中列出的属性将不会包含在模型的序列化表示中

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<string>
     */
    protected $hidden = ['password'];
}

或者，您可以使用 visible 属性来定义应包含在模型的数组和 JSON 表示中的属性的“允许列表”。当模型转换为数组或 JSON 时，$visible 数组中不存在的所有属性都将被隐藏

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The attributes that should be visible in arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

临时修改属性可见性

如果您想在给定的模型实例上显示一些通常隐藏的属性，可以使用 makeVisible 方法。makeVisible 方法返回模型实例

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

同样，如果您想隐藏一些通常可见的属性，可以使用 makeHidden 方法。

return $user->makeHidden('attribute')->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
{
    /**
     * Determine if the user is an administrator.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

如果您希望访问器始终附加到模型的数组和 JSON 表示形式中，可以将属性名称添加到模型的 appends 属性中。请注意，即使访问器的 PHP 方法是使用“驼峰式命名法”定义的，属性名称通常使用它们的“蛇形命名法”序列化表示形式来引用

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The accessors to append to the model's array form.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

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

在运行时追加

在运行时，您可以使用 append 方法指示模型实例追加其他属性。或者，您可以使用 setAppends 方法覆盖给定模型实例的整个附加属性数组

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

日期序列化

自定义默认日期格式

您可以通过覆盖 serializeDate 方法来自定义默认序列化格式。此方法不会影响日期在数据库中的存储格式

/**
 * Prepare a date for array / JSON serialization.
 */
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',
    ];
}