Eloquent: 序列化

简介

当你在创建 JSON API 的时候，经常会需要将模型和关联转换成数组或 JSON。Eloquent 提供了一些便捷的方法来让我们可以完成这些转换，以及控制哪些属性需要被包括在序列化中。

序列化模型 & 集合

序列化成数组

如果要将模型还有其加载的 关联 转换成一个数组，则可以使用 toArray 方法。这个方法是递归的，因此，所有属性和关联（包含关联中的关联）都会被转换成数组：

  1. $user = App\User::with('roles')->first();
  3. return $user->toArray();

你也可以将整个 集合 转换成数组：

  1. $users = App\User::all();
  3. return $users->toArray();

序列化成 JSON

如果要将模型转换成 JSON，则可以使用 toJson 方法。如同 toArray 方法一样，toJson 方法也是递归的。因此，所有的属性以及关联都会被转换成 JSON：

  1. $user = App\User::find(1);
  3. return $user->toJson();

或者，你也可以强制把一个模型或集合转型成一个字符串，它将会自动调用 toJson 方法：

  1. $user = App\User::find(1);
  3. return (string) $user;

当模型或集合被转型成字符串时，模型或集合便会被转换成 JSON 格式，因此你可以直接从应用程序的路由或者控制器中返回 Eloquent 对象：

  1. Route::get('users', function () {
  2.     return App\User::all();
  3. });

隐藏来自 JSON 的属性

有时候你可能会想要限制包含在模型数组或 JSON 表示中的属性，比如说密码。则可以通过在模型中增加 $hidden 属性定义来实现：

  1. <?php
  3. namespace App;
  5. use Illuminate\Database\Eloquent\Model;
  7. class User extends Model
  8. {
  9.     /**
  10.      * 在数组中想要隐藏的属性。
  11.      *
  12.      * @var array
  13.      */
  14.     protected $hidden = ['password'];
  15. }

{note} 当你要对关联进行隐藏时，需使用关联的 方法 名称，而不是它的动态属性名称。

另外，你也可以使用 visible 属性来定义应该包含在你的模型数组和 JSON 表示中的属性白名单。白名单外的其他属性将隐藏，不会出现在转换后的数组或 JSON 中：

  1. <?php
  3. namespace App;
  5. use Illuminate\Database\Eloquent\Model;
  7. class User extends Model
  8. {
  9.     /**
  10.      * 在数组中可见的属性。
  11.      *
  12.      * @var array
  13.      */
  14.     protected $visible = ['first_name', 'last_name'];
  15. }

临时修改属性的可见度

你可以在模型实例后使用 makeVisible 方法来显示通常隐藏的属性，且为了便于使用，makeVisible 方法会返回一个模型实例：

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

相应的，你可以在模型实例后使用 makeHidden 方法来隐藏通常显示的属性：

  1. return $user->makeHidden('attribute')->toArray();

添加参数到 JSON 中

有时候，在转换模型到 数组 或 JSON 时，你希望添加一个在数据库中没有对应字段的属性。首先你需要为这个值定义一个 访问器 ：

  1. <?php
  3. namespace App;
  5. use Illuminate\Database\Eloquent\Model;
  7. class User extends Model
  8. {
  9.     /**
  10.      * 为用户获取管理者的标记。
  11.      *
  12.      * @return bool
  13.      */
  14.     public function getIsAdminAttribute()
  15.     {
  16.         return $this->attributes['admin'] == 'yes';
  17.     }
  18. }

访问器创建成功后，只需添加该属性到改模型的 appends 属性中。注意，属性名称通常遵循 「Snake Case」 的命名方式，即是访问器的名称是基于 「Camel Case」 的命名方式。

  1. <?php
  3. namespace App;
  5. use Illuminate\Database\Eloquent\Model;
  7. class User extends Model
  8. {
  9.     /**
  10.      * 访问器被附加到模型数组的形式。
  11.      *
  12.      * @var array
  13.      */
  14.     protected $appends = ['is_admin'];
  15. }

一旦属性被添加到 appends 清单，便会将模型中的数组和 JSON 这两种形式都包含进去。在 appends 数组中的属性也遵循模型中 visible 和 hidden 设置。

译者署名

用户名 头像 职能 签名
@skyverd 序列化 - 图1 翻译 全桟工程师，时光博客

{note} 欢迎任何形式的转载，但请务必注明出处，尊重他人劳动共创开源社区。

转载请注明：本文档由 Laravel China 社区 [laravel-china.org] 组织翻译，详见 翻译召集帖。

文档永久地址： http://d.laravel-china.org