在使用 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);
Route::get('/users', function () {
return User::all();
});
控制属性的显示
隐藏属性
有时希望在模型的数组或 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 属性列表中的属性在序列化时会被隐藏。
<?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 时，有时希望加入一些在数据库中并没有对应列的属性。
首先需要定义相应的访问器。
<?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',
);
}
}
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');
}
每个属性的日期格式
也可以在模型的类型转换声明中为单个日期属性指定序列化格式。
protected function casts(): array
{
return [
'birthday' => 'date:Y-m-d',
'joined_at' => 'datetime:Y-m-d H:00',
];
}
