Eloquent: 序列化

簡介

當你在建立 JSON APIs 的時候,經常需要將模型和關聯轉換成陣列或是 JSON。Eloquent 提供了一些方便的方法讓我們可以做這些轉換,以及控制哪些屬性要包括在你的序列化中。

基本用法

將模型轉換成一個陣列

如果要將模型還有它載入的關聯轉換成一個陣列,你可以使用 toArray 方法。這個方法是遞迴的,因此,所有屬性和所有關聯(包含關聯中的關聯)都會被轉換成陣列:

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

return $user->toArray();

你也可以將集合轉換成陣列:

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

return $users->toArray();

將模型轉換成 JSON

如果要將模型轉換成 JSON,你可以使用 toJson 方法。如同 toArraytoJson 方法也是遞迴的,所以,所有的屬性以及關聯都將被轉換成 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'];
}

添加一些值到 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 陣列中的屬性也遵循模型中 visiblehidden 的設定。