Eloquent: Serialization

Introduction

Laravel を使用して API を構築する際、しばしば models や関連付けを配列や JSON に変換する必要があります。 Eloquent には、これらの変換を行うための便利な方法が含まれており、 models のシリアル化された表現に含まれる attributes を制御することも可能です。

NOTE

さらに強力な方法で Eloquent model と collection JSON のシリアライズを処理するには、Eloquent API resourcesのドキュメンテーションをご覧ください。

Serializing Models and Collections

配列へのシリアライズ

model とその読み込まれたrelationshipsを attributes に変換するには、toArray method を使用する必要があります。この method は再帰的で、すべての属性とすべての関係(関係の関係を含む)が array に変換されます。

use App\Models\User;

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

return $user->toArray();

attributesToArray method は model の attributes を array に変換するために使用できますが、その関連性は変換できません：

$user = User::first();

return $user->attributesToArray();

あなたはまた、toArray method を collection のインスタンスに適用することで、全体のcollectionsを models の arrays に変換することもできます：

$users = User::all();

return $users->toArray();

JSON へのシリアライズ

model を JSON に変換するには、toJson method を使用すべきです。toArrayのように、toJson method は再帰的であるため、すべての attributes と関連性が JSON に変換されます。また、PHP でサポートされている JSON のエンコーディング options も指定することができます。

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

あるいは、 model または collection を string にキャストすることもできます。これにより、toJson method が model または collection 上で自動的に呼び出されます。

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

models や collections は string にキャストされるときに JSON に変換されるため、 Eloquent のオブジェクトをアプリケーションの routes やコントローラから直接返すことができます。 Laravel は、 routes やコントローラから返された Eloquent models や collections が JSON に自動的にシリアライズされます。

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

Relationships

Eloquent model が JSON に変換されると、ロードされた関連性が自動的に JSONobject の属性に含まれます。また、Eloquent のリレーションシップ方法は camel case の method 名を使用して定義されますが、リレーションシップの JSON 属性は"snake case"になります。

Hiding Attributes From JSON

場合によっては、モデルの array または JSON 表現に含まれる Attributes (例えば passwords )を制限したいと思うかもしれません。そのためには、あなたの model に $hidden プロパティを追加してください。 attributes は $hidden プロパティの array にリストされ、あなたの model のシリアライズされた表現には含まれません。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = ['password'];
}

NOTE

関係を非表示にするには、関係の method 名を Eloquent モデルの$hiddenプロパティに追加してください。

あるいは、visibleプロパティを使用して、モデルの array や JSON 表現に含めるべき attributes の"許可リスト"を定義することもできます。$visible array に存在しないすべての attributes は、 model が array や JSON に変換されるときに hidden になります。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The attributes that should be visible in arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

一時的に Attribute の可視性を変更する

もし特定の model インスタンス上で通常 hidden attributes とされるいくつかの属性を表示したい場合は、makeVisible method を使用できます。makeVisible method は model インスタンスを返します：

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

同様に、通常は見える 属性 の一部を隠したい場合は、makeHidden method を使用することができます。

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

すべての表示属性または hidden attributes を一時的に上書きしたい場合は、それぞれsetVisibleメソッドとsetHiddenメソッドを使用することができます：

return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();

Appending Values to JSON

時折、 models を配列や JSON に変換する際に、 database の対応する column がない attributes を追加したいと思うことがあるかもしれません。それを行うには、まず value のためのアクセサを定義します。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Determine if the user is an administrator.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

あなたが model の array や JSON 表現に常にアクセサーを付加したい場合は、model のappendsプロパティに attribute の名前を追加できます。attribute の名前は、通常、"snake case"のシリアライズされた表現を使って参照されます。これは、アクセサーの PHP の method が"camel case"で定義されているにも関わらずです。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The accessors to append to the model's array form.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

appendsリストに attribute が追加されると、model の array と JSON の表現の両方に含まれます。appendsarray の Attributes は、model の設定で設定されたvisibleとhiddenを尊重します。

実行時に追加する

runtime の際、 model インスタンスにappend method を使用して追加の attributes を append するよう指示することができます。 または、特定の model インスタンスの追加されたプロパティの全体の array を上書きするために、setAppends method を使用することもできます。

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

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

Date Serialization

Default 日付形式のカスタマイズ

default のシリアライゼーション形式は、serializeDatemethod を上書きすることでカスタマイズできます。この method は、database に格納するための日付の形式には影響しません。

/**
 * Prepare a date for array / JSON serialization.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

Attribute ごとの日付形式のカスタマイズ

モデルのキャスト宣言で日付フォーマットを指定することにより、個々の Eloquent 日付 attributes のシリアライズ形式をカスタマイズすることができます：

protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}