Eloquent: 序列化

简介

构建 JSON API 时,经常需要把模型和关联转化为数组或 JSON。针对这些操作,Eloquent 提供了一些便捷方法,以及对序列化中的属性控制。

序列化模型 & 集合

序列化为数组

要转化模型及其加载的 关联 为数组,可以使用 toArray 方法。这是一个递归的方法,因此所有的属性和关联(包括关联的关联)都将转化成数组:

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

可以转化模型的单个实例为数组:

  1. $user = App\User::first();
  2. return $user->attributesToArray();

也可以转化整个模型 集合 为数组:

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

序列化为 JSON

方法 toJson 可以把模型转化成 JSON。和方法 toArray 一样, toJson 方法也是递归的,因此所有属性和关联都会转化成 JSON, 你还可以指定由 PHP 支持的 JSON 编码选项

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

也可以把模型或集合转成字符串,方法 toJson 将自动调用:

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

由于模型和集合在转化为字符串的时候会转成 JSON, 因此可以在应用的路由或控制器中直接返回 Eloquent 对象:

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

关联关系

当一个模型被转化为JSON的时候,它加载的关联关系也将自动转化为JSON对象被包含进来。同时,通过小驼峰定义的关联方法,关联的JSON属性将会是蛇形命名。

隐藏 JSON 属性

有时要将模型数组或 JSON 中的某些属性进行隐藏,比如密码,则可以在模型中添加 $hidden 属性:

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

注意:隐藏关联时,需使用关联的方法名。

此外,也可以使用属性 $visible 定义一个模型数组和 JSON 可见的白名单。转化后的数组或 JSON 不会出现其他的属性:

  1. <?php
  2. namespace App;
  3. use Illuminate\Database\Eloquent\Model;
  4. class User extends Model
  5. {
  6. /**
  7. * 数组中的属性会被展示。
  8. *
  9. * @var array
  10. */
  11. protected $visible = ['first_name', 'last_name'];
  12. }

临时修改可见属性

如果你想要在一个模型实例中显示隐藏的属性,你可以使用 makeVisible 方法。makeVisible 方法返回模型实例:

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

相应地,如果你想要在一个模型实例中隐藏可见的属性,你可以使用 makeHidden 方法。

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

追加 JSON 值

有时,需要在数组或 JSON 中添加一些数据库中不存在字段的对应属性。要实现这个功能,首先要定义一个 修改器

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

然后,在模型属性 appends 中添加该属性名。注意,尽管访问器使用「驼峰命名法」方式定义,但是属性名通常以「蛇形命名法」的方式来引用:

  1. <?php
  2. namespace App;
  3. use Illuminate\Database\Eloquent\Model;
  4. class User extends Model
  5. {
  6. /**
  7. * 追加到模型数组表单的访问器。
  8. *
  9. * @var array
  10. */
  11. protected $appends = ['is_admin'];
  12. }

使用 append 方法追加属性后,它将包含在模型的数组和 JSON 中。appends 数组中的属性也将遵循模型上配置的 visiblehidden 设置。

运行时追加

你可以在单个模型实例上使用 append 方法来追加属性。或者,使用 setAppends 方法来重写整个追加属性的数组:

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

序列化日期

自定义任意属性的日期格式

你可以在 Eloquent 的 属性类型转换 中单独为日期属性自定义日期格式:

  1. protected $casts = [
  2. 'birthday' => 'date:Y-m-d',
  3. 'joined_at' => 'datetime:Y-m-d H:00',
  4. ];

Carbon 全局自定义

Laravel 扩展了 Carbon 日期库来为 Carbon的 JSON 序列化提供便利。可以使用 Carbon::serializeUsing 方法来自定义所有 Carbon 日期在整个应用中的序列化。serializeUsing 方法接受一个闭包,该闭包返回一个字符串形式的日期:

  1. <?php
  2. namespace App\Providers;
  3. use Illuminate\Support\Carbon;
  4. use Illuminate\Support\ServiceProvider;
  5. class AppServiceProvider extends ServiceProvider
  6. {
  7. /**
  8. * 在服务容器中注册绑定。
  9. *
  10. * @return void
  11. */
  12. public function register()
  13. {
  14. //
  15. }
  16. /**
  17. * 执行注册后,启动服务。
  18. *
  19. * @return void
  20. */
  21. public function boot()
  22. {
  23. Carbon::serializeUsing(function ($carbon) {
  24. return $carbon->format('U');
  25. });
  26. }
  27. }

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接 我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。