序列化
简介
在使用 Laravel 构建 API 时，你经常需要将模型和关系转换为数组或 JSON。Eloquent 包含了进行这些转换的便捷方法，以及控制模型序列化表示中包含哪些属性的方法。
信息
要获得更强大的 Eloquent 模型和集合 JSON 序列化处理方式，请查看 Eloquent API 资源文档。
典型业务场景：
- API 响应脱敏：通过
#[Hidden(['password', 'remember_token'])]确保用户模型在序列化为 JSON 时永远不会泄露密码和令牌字段 - 前端字段白名单：使用
#[Visible(['name', 'avatar', 'bio'])]只向公开个人主页接口暴露有限字段，避免内部数据外泄 - 计算字段追加：通过
#[Appends(['is_admin', 'full_name'])]让模型每次序列化时自动携带访问器计算出的虚拟属性，无需前端二次拼接 - 日期格式统一：通过
serializeDate方法将全部日期字段统一输出为Y-m-d格式，确保前端无需处理 ISO-8601 时区字符串 - 运行时动态控制：管理后台接口使用
makeVisible('email')临时显示邮箱，而公开接口保持隐藏，同一模型适配不同权限场景 - 关联数据一并输出：调用
toArray()递归将模型及其所有已加载关系转为数组，一次返回完整数据结构给前端
序列化模型与集合
序列化为数组
要将模型及其已加载的关系转换为数组，你应该使用 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 表示中的属性「允许列表」。当模型转换为数组或 JSON 时，不存在于 Visible 属性中的所有属性都将被隐藏：
<?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',
];
}