Eloquent: 序列化

• 介绍
• 基本用法
• 从 JSON 中隐藏属性
• 向 JSON 中追加值

介绍

在构建 JSON API 时，您通常需要将模型及其关系转换为数组或 JSON。Eloquent 提供了方便的方法来进行这些转换，并控制哪些属性包含在序列化中。

基本用法

将模型转换为数组

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

$user = App\User::with('roles')->first();

return $user->toArray();

您还可以将集合转换为数组：

$users = App\User::all();

return $users->toArray();

将模型转换为 JSON

要将模型转换为 JSON，可以使用 toJson 方法。与 toArray 类似，toJson 方法是递归的，因此所有属性和关系都将被转换为 JSON：

$user = App\User::find(1);

return $user->toJson();

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

$user = App\User::find(1);

return (string) $user;

由于模型和集合在转换为字符串时会被转换为 JSON，您可以直接从应用程序的路由或控制器返回 Eloquent 对象：

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

从 JSON 中隐藏属性

有时您可能希望限制模型的数组或 JSON 表示中包含的属性，例如密码。为此，请在模型中添加一个 $hidden 属性定义：

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 应该在数组中隐藏的属性。
     *
     * @var array
     */
    protected $hidden = ['password'];
}

隐藏关系时，请使用关系的方法名称，而不是其动态属性名称。

或者，您可以使用 visible 属性定义一个白名单，以确定应包含在模型的数组和 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'];
}

一旦将属性添加到 appends 列表中，它将在模型的数组和 JSON 形式中包含。appends 数组中的属性也将遵循模型上配置的 visible 和 hidden 设置。