laravelphp 中文文档      >

简介

使用 Laravel 构建 API 时，您经常需要将模型和关系转换为数组或 JSON。Eloquent 包含进行这些转换的便捷方法，以及控制哪些属性包含在模型的序列化表示中。


有关处理 Eloquent 模型和集合 JSON 序列化的更强大方法，请查看 Eloquent API 资源.

序列化模型 & 集合

序列化为数组

要将模型加载的关系转换为数组，应使用 php toArray 方法。此方法是递归的，因此所有属性和所有关系（包括关系的关系）都将转换为数组：

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

php attributesToArray 方法可用于将模型的属性转换为数组，但不能将其关系转换为数组：

  1. $user = User::first();
  3. return $user->attributesToArray();

还可以通过调用集合实例上的 php toArray 方法将模型的整个 集合 转换为数组：

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

序列化为JSON

要将模型转换为 JSON，您应该使用 php toJson 方法。与 php toArray 一样，php toJson 方法是递归的，因此所有属性和关系都将转换为 JSON。您还可以指定 PHP 支持的 的任何 JSON 编码选项：

  1. use App\Models\User;
  3. $user = User::find(1);
  5. return $user->toJson();
  7. return $user->toJson(JSON_PRETTY_PRINT);

或者，您可以将模型或集合转换为字符串，这将自动调用模型或集合上的php toJson方法：

  1. return (string) User::find(1);

由于模型和集合在转换为字符串时会转换为 JSON，因此您可以直接从应用程序的路由或控制器返回 Eloquent 对象。当从路由或控制器返回 Eloquent 模型和集合时，Laravel 会自动将它们序列化为 JSON：

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

关联关系
当 Eloquent 模型转换为 JSON 时，其加载的关系将自动作为属性包含在 JSON 对象中。此外，尽管 Eloquent 关系方法是使用php 驼峰式方法名称定义的，但关系的 JSON 属性将采用php 蛇形式。

隐藏 JSON 属性

有时您可能希望限制模型数组或 JSON 表示中包含的属性（例如密码）。为此，请向您的模型添加 php $hidden 属性。php $hidden 属性数组中列出的属性将不会包含在模型的序列化表示中：

  1. <?php
  3. namespace App\Models;
  5. use Illuminate\Database\Eloquent\Model;
  7. class User extends Model
  8. {
  9.     /**
  10.      * The attributes that should be hidden for arrays.
  11.      *
  12.      * @var array
  13.      */
  14.     protected $hidden = ['password'];
  15. }


要隐藏关系，请将关系的方法名称添加到 Eloquent 模型的php $hidden属性中。


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

  1. <?php
  3. namespace App\Models;
  5. use Illuminate\Database\Eloquent\Model;
  7. class User extends Model
  8. {
  9.     /**
  10.      * The attributes that should be visible in arrays.
  11.      *
  12.      * @var array
  13.      */
  14.     protected $visible = ['first_name', 'last_name'];
  15. }

临时修改可见属性
如果你想要在一个模型实例中显示隐藏的属性，可以使用 php makeVisible 方法。php makeVisible 方法返回模型实例：

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

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

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

如果你希望暂时覆盖所有可见或隐藏属性，你可以分别使用 php setVisible 和 php setHidden 方法：

  1. return $user->setVisible(['id', 'name'])->toArray();
  3. return $user->setHidden(['email', 'password', 'remember_token'])->toArray();

追加 JSON 值

有时，在将模型转换为数组或 JSON 时，你可能希望添加数据库中没有对应列的属性。为此，首先为该值定义一个 访问器：

  1. <?php
  3. namespace App\Models;
  5. use Illuminate\Database\Eloquent\Casts\Attribute;
  6. use Illuminate\Database\Eloquent\Model;
  8. class User extends Model
  9. {
  10.     /**
  11.      * 确定用户是否为管理员
  12.      */
  13.     protected function isAdmin(): Attribute
  14.     {
  15.         return new Attribute(
  16.             get: fn () => 'yes',
  17.         );
  18.     }
  19. }

如果你希望访问器始终附加到模型的数组和 JSON 表示，则可以将属性名称添加到模型的「appends」属性中。请注意，属性名称通常使用其「蛇形命名法」序列化表示来引用，即使访问器的 PHP 方法是使用「驼峰命名法」定义的：

  1. <?php
  3. namespace App\Models;
  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. }

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

运行时追加
在运行时，你可以指示模型实例使用 php append 方法附加其他属性。或者，您可以使用 php setAppends 方法来覆盖给定模型实例的整个附加属性数组：

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

日期序列化

自定义默认日期格式
可以通过重写 php serializeDate 方法来自定义默认序列化格式。此方法不会影响日期在数据库中的存储格式：

  1. /**
  2.  * 准备一个用于数组 / JSON 序列化
  3.  */
  4. protected function serializeDate(DateTimeInterface $date): string
  5. {
  6.     return $date->format('Y-m-d');
  7. }

自定义默认日期格式
可以通过在模型的 转换声明 中指定日期格式来自定义单个 Eloquent 日期属性的序列化格式：

  1. protected function casts(): array
  2. {
  3.     return [
  4.         'birthday' => 'date:Y-m-d',
  5.         'joined_at' => 'datetime:Y-m-d H:00',
  6.     ];
  7. }