序列化

Laravel 中文文档 / Eloquent ORM

Eloquent:序列化

简介

构建 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。也可以指定 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();
});

隐藏 JSON 属性

有时可能希望限制模型转换为数组或 JSON 形式时包含的属性,例如密码。要完成此操作,可以在模型中添加一个 $hidden 属性:

namespace App;

use Illuminate\Database\Eloquent\Model;

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

隐藏关联时,可以使用关联的方法名。

或者,可以使用 visible 属性定义一个模型转换为数组或 JSON 形式时包含的属性白名单。当模型被转换为数组或 JSON 时,白名单以外的属性都会被隐藏:

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 时,有时可能希望添加数据库中不存在的属性。要完成此操作,首先定义为其一个 修改器

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 获取用户的管理员标识
     *
     * @return bool
     */
    public function getIsAdminAttribute()
    {
        return $this->attributes['admin'] == 'yes';
    }
}

创建修改器后,将属性名添加到模型上的 appends 属性。需要注意的是,属性名通常使用「蛇形命名法」引用,即使修改器使用「驼峰命名法」定义:

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 追加到模型数组的修改器
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

添加属性到 appends 列表后,它会自动包含在模型的数组和 JSON 形式中。appends 数组中的属性也遵从模型上的 visiblehidden 设置。

运行时追加

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

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

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

日期序列化

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

可以通过在 cast 声明 中指定日期格式自定义每个 Eloquent 日期属性的序列化格式:

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

通过 Carbon 全局自定义

Laravel 继承了 Carbon 日期库以便自定义 Carbon 的 JSON 序列化格式。要自定义应用中所有 Carbon 日期如何序列化,可以使用 Carbon::serializeUsing 方法。Carbon::serializeUsing 方法接收一个闭包,闭包返回 JSON 序列化后表示的日期的字符串:

namespace App\Providers;

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

class AppServiceProvider extends ServiceProvider
{
    /**
     * 注册后启动服务
     *
     * @return void
     */
    public function boot()
    {
        Carbon::serializeUsing(function ($carbon) {
            return $carbon->format('U');
        });
    }

    /**
     * 注册容器绑定
     *
     * @return void
     */
    public function register()
    {
        //
    }
}
  上一篇 下一篇  

作者:ilaoniu

牛哥,俗称哞哞。单纯的九零后理工小青年。喜欢折腾,爱玩,爱安卓,爱音乐,爱游戏,爱电影,爱旅游...