【laravel7.x中文文档】序列化
构建 JSON API 时,经常需要把模型和关联转化为数组或 JSON。针对这些操作,Eloquent 提供了一些便捷方法,以及对序列化中的属性控制。
要转化模型及其加载的 关联为数组,可以使用 toArray
方法。这是一个递归的方法,因此所有的属性和关联(包括关联的关联)都将转化成数组:
$user = App\User::with('roles')->first();
return $user->toArray();
可以转化模型的单个实例为数组:
$user = App\User::first();
return $user->attributesToArray();
也可以转化整个模型集合为数组:
$users = App\User::all();
return $users->toArray();
方法 toJson
可以把模型转化成 JSON。和方法 toArray
一样, toJson
方法也是递归的,因此所有属性和关联都会转化成 JSON, 你还可以指定由 PHP 支持的 JSON 编码选项:
$user = App\User::find(1);
return $user->toJson();
return $user->toJson(JSON_PRETTY_PRINT);
也可以把模型或集合转成字符串,方法 toJson
将自动调用:
$user = App\User::find(1);
return (string) $user;
由于模型和集合在转化为字符串的时候会转成 JSON, 因此可以在应用的路由或控制器中直接返回 Eloquent 对象:
Route::get('users', function () {
return App\User::all();
});
当一个模型被转化为JSON的时候,它加载的关联关系也将自动转化为JSON对象被包含进来。同时,通过小驼峰定义的关联方法,关联的JSON属性将会是蛇形命名。
有时要将模型数组或 JSON 中的某些属性进行隐藏,比如密码,则可以在模型中添加 $hidden
属性:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 数组中的属性会被隐藏
*
* @var array
*/
protected $hidden = ['password'];
}
注意:隐藏关联时,需使用关联的方法名。
此外,也可以使用属性 $visible
定义一个模型数组和 JSON 可见的白名单。转化后的数组或 JSON 不会出现其他的属性:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 数组中的属性会被展示。
*
* @var array
*/
protected $visible = ['first_name', 'last_name'];
}
如果你想要在一个模型实例中显示隐藏的属性,你可以使用 makeVisible
方法。makeVisible
方法返回模型实例:
return $user->makeVisible('attribute')->toArray();
相应地,如果你想要在一个模型实例中隐藏可见的属性,你可以使用 makeHidden
方法。
return $user->makeHidden('attribute')->toArray();
有时,需要在数组或 JSON 中添加一些数据库中不存在字段的对应属性。要实现这个功能,首先要定义一个修改器。
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 为用户获取管理员标识。
*
* @return bool
*/
public function getIsAdminAttribute()
{
return $this->attributes['admin'] === 'yes';
}
}
然后,在模型属性 appends
中添加该属性名。注意,尽管访问器使用「驼峰命名法」方式定义,但是属性名通常以「蛇形命名法」的方式来引用:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 追加到模型数组表单的访问器。
*
* @var array
*/
protected $appends = ['is_admin'];
}
使用 append
方法追加属性后,它将包含在模型的数组和 JSON 中。appends
数组中的属性也将遵循模型上配置的 visible
和 hidden
设置。
你可以在单个模型实例上使用 append
方法来追加属性。或者,使用 setAppends
方法来重写整个追加属性的数组:
return $user->append('is_admin')->toArray();
return $user->setAppends(['is_admin'])->toArray();
你可以通过覆盖 serializeDate
方法自定义默认的序列化格式:
/**
* 为数组/ JSON序列化准备一个日期。
*
* @param \DateTimeInterface $date
* @return string
*/
protected function serializeDate(DateTimeInterface $date)
{
return $date->format('Y-m-d');
}
你可以在 Eloquent 的 属性类型转换 中单独为日期属性自定义日期格式:
protected $casts = [
'birthday' => 'date:Y-m-d',
'joined_at' => 'datetime:Y-m-d H:00',
];