Documentation Index
Fetch the complete documentation index at: https://kawax.biz/llms.txt
Use this file to discover all available pages before exploring further.
はじめに
LaravelでAPIを構築する際、モデルとそのリレーションを配列やJSONに変換する必要がよくあります。
Eloquentにはこれらの変換を行うための便利なメソッドと、シリアライズされたモデルの表現にどの属性を含めるかを制御する機能が含まれています。
Eloquentモデルとコレクションのより堅牢なJSONシリアライゼーションの方法については、Eloquent APIリソースのドキュメントを参照してください。 モデルと配列
配列へのシリアライゼーション
モデルと読み込まれたリレーションを配列に変換するには toArray メソッドを使います。
このメソッドは再帰的に動作し、すべての属性とすべてのリレーション（リレーションのリレーションも含む）が配列に変換されます。
use App\Models\User;
$user = User::with('roles')->first();
return $user->toArray();
attributesToArray メソッドを使うと、リレーションを除いたモデルの属性だけを配列に変換できます。
$user = User::first();
return $user->attributesToArray();
toArray メソッドを呼び出します。
$users = User::all();
return $users->toArray();
JSONへのシリアライゼーション
モデルをJSONに変換するには toJson メソッドを使います。
toArray と同様に toJson メソッドも再帰的なので、すべての属性とリレーションがJSONに変換されます。
PHPがサポートするJSONエンコードオプションを指定することもできます。
use App\Models\User;
$user = User::find(1);
return $user->toJson();
return $user->toJson(JSON_PRETTY_PRINT);
toJson メソッドが自動的に呼び出されます。
return (string) User::find(1);
Route::get('/users', function () {
return User::all();
});
リレーション
EloquentモデルがJSONに変換される際、読み込まれたリレーションはJSONオブジェクトの属性として自動的に含まれます。
また、Eloquentのリレーションメソッドは「キャメルケース」のメソッド名で定義されますが、リレーションのJSON属性は「スネークケース」になります。
属性の表示制御
属性の非表示
モデルの配列またはJSON表現に含まれるパスワードなどの属性を制限したい場合があります。
そのためにはモデルに Hidden 属性を使います。
Hidden 属性にリストされた属性はモデルのシリアライズされた表現に含まれません。
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;
#[Hidden(['password'])]
class User extends Model
{
// ...
}
リレーションを非表示にするには、EloquentモデルのHidden属性にリレーションのメソッド名を追加します。
属性の公開
Visible 属性を使って、モデルの配列およびJSON表現に含まれるべき属性の「許可リスト」を定義することもできます。
Visible 属性に存在しないすべての属性は、モデルが配列やJSONに変換される際に非表示になります。
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;
#[Visible(['first_name', 'last_name'])]
class User extends Model
{
// ...
}
属性の一時的な表示・非表示
通常は非表示になっている属性を特定のモデルインスタンスで表示させるには、makeVisible または mergeVisible メソッドを使います。
makeVisible メソッドはモデルインスタンスを返します。
return $user->makeVisible('attribute')->toArray();
return $user->mergeVisible(['name', 'email'])->toArray();
makeHidden または mergeHidden メソッドを使います。
return $user->makeHidden('attribute')->toArray();
return $user->mergeHidden(['name', 'email'])->toArray();
setVisible および setHidden メソッドをそれぞれ使います。
return $user->setVisible(['id', 'name'])->toArray();
return $user->setHidden(['email', 'password', 'remember_token'])->toArray();
追加属性
モデルを配列やJSONに変換する際、データベースに対応するカラムを持たない属性を追加したい場合があります。
そのためにはまず値のアクセサを定義します。
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* ユーザーが管理者かどうかを判定する。
*/
protected function isAdmin(): Attribute
{
return new Attribute(
get: fn () => 'yes',
);
}
}
Appends 属性を使います。
アクセサのPHPメソッドは「キャメルケース」で定義されていますが、属性名は通常「スネークケース」でのシリアライズ表現を使います。
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;
#[Appends(['is_admin'])]
class User extends Model
{
// ...
}
appends リストに追加されると、モデルの配列とJSON表現の両方に含まれます。
appends 配列の属性もモデルに設定された visible と hidden の設定を尊重します。
実行時の追加
実行時に append または mergeAppends メソッドを使ってモデルインスタンスに追加の属性を追加するよう指示できます。
また setAppends メソッドを使って、特定のモデルインスタンスの追加プロパティの配列全体をオーバーライドできます。
return $user->append('is_admin')->toArray();
return $user->mergeAppends(['is_admin', 'status'])->toArray();
return $user->setAppends(['is_admin'])->toArray();
withoutAppends メソッドを使います。
return $user->withoutAppends()->toArray();
日付のシリアライゼーション
デフォルトの日付フォーマットのカスタマイズ
serializeDate メソッドをオーバーライドすることで、デフォルトのシリアライゼーションフォーマットをカスタマイズできます。
このメソッドはデータベースへの保存のための日付フォーマットには影響しません。
/**
* 配列・JSONシリアライゼーションのために日付を準備する。
*/
protected function serializeDate(DateTimeInterface $date): string
{
return $date->format('Y-m-d');
}
属性ごとの日付フォーマットのカスタマイズ
モデルのキャスト宣言で日付フォーマットを指定することで、個々のEloquent日付属性のシリアライゼーションフォーマットをカスタマイズできます。
protected function casts(): array
{
return [
'birthday' => 'date:Y-m-d',
'joined_at' => 'datetime:Y-m-d H:00',
];
}
