Eloquent: 序列化

• 介绍
• 序列化模型和集合
  • 序列化为数组
  • 序列化为 JSON
• 从 JSON 中隐藏属性
• 向 JSON 添加值
• 日期序列化

介绍

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

序列化模型和集合

序列化为数组

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

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

return $user->toArray();

要仅将模型的属性转换为数组，请使用 attributesToArray 方法：

$user = App\User::first();

return $user->attributesToArray();

您还可以将整个集合的模型转换为数组：

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

return $users->toArray();

序列化为 JSON

要将模型转换为 JSON，您应该使用 toJson 方法。与 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();
});

关系

当 Eloquent 模型被转换为 JSON 时，其加载的关系将自动作为属性包含在 JSON 对象中。此外，尽管 Eloquent 关系方法是使用“驼峰命名法”定义的，但关系的 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 添加值

有时，在将模型转换为数组或 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 设置。

运行时附加

您可以使用 append 方法指示单个模型实例附加属性。或者，您可以使用 setAppends 方法覆盖给定模型实例的整个附加属性数组：

return $user->append('is_admin')->toArray();

return $user->setAppends(['is_admin'])->toArray();

日期序列化

自定义每个属性的日期格式

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

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

通过 Carbon 全局自定义

Laravel 扩展了 Carbon 日期库，以便提供方便的 Carbon JSON 序列化格式自定义。要自定义应用程序中所有 Carbon 日期的序列化方式，请使用 Carbon::serializeUsing 方法。serializeUsing 方法接受一个闭包，该闭包返回用于 JSON 序列化的日期字符串表示：

<?php

namespace App\Providers;

use Illuminate\Support\Carbon;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 在容器中注册绑定。
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * 启动任何应用程序服务。
     *
     * @return void
     */
    public function boot()
    {
        Carbon::serializeUsing(function ($carbon) {
            return $carbon->format('U');
        });
    }
}