Laravel 7.x Eloquent:シリアライズ

イントロダクション

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'];
}

Note: リレーションを含めない場合は、メソッド名を指定してください。

もしくはモデルを変換後の配列やJSONに含めるべき属性のホワイトリストを定義する、visibleプロパティを使用してください。モデルが配列やJSONへ変換される場合、その他の属性はすべて、変換結果に含まれません。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 配列中に含める属性
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

プロパティ配列出力管理の一時的変更

特定のモデルインスタンスにおいて、通常は配列に含めない属性を含めたい場合は、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配列の属性もモデルのvisiblehiddenの設定に従い動作します。

実行時の追加

一つのモデルインスタンスに対し、appendメソッドにより属性を追加するように指示できます。もしくは、指定したモデルに対して、追加するプロパティの配列全体をオーバーライドするために、setAppendsメソッドを使用します。

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

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

日付のシリアライズ

デフォルト日付形式のカスタマイズ

serializeDateメソッドをオーバーライドすることにより、デフォルトの日付位形式をカスタマイズできます。

/**
 * 配列/日付シリアライズのために日付を準備
 *
 * @param  \DateTimeInterface  $date
 * @return string
 */
protected function serializeDate(DateTimeInterface $date)
{
    return $date->format('Y-m-d');
}

属性ごとに日付形式をカスタマイズ

キャスト宣言で日付形式を指定することにより、Eloquent日付属性ごとにシリアライズ形式をカスタマイズできます。

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

ドキュメント章別ページ

ヘッダー項目移動

注目:アイコン:ページ内リンク設置(リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

PDC

ページ(章)移動の左オフキャンバスオープン

HA

ヘッダー移動モーダルオープン

MS

移動/設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

NJ

次ヘッダー(H2〜H4)へ移動

BK

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる