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

イントロダクションIntroduction

JSONでAPIを作成する場合にはモデルとリレーションを配列やJSONに変換する必要が良く起きます。そのためEloquentはシリアライズ結果にどの属性を含むかをコントロールしながら、変換を行う便利なメソッドを含んでいますWhen building JSON APIs, you will often need to convert your models and relationships to arrays or JSON. Eloquent includes convenient methods for making these conversions, as well as controlling which attributes are included in your serializations.

モデルとコレクションのシリアライズSerializing Models & Collections

配列へのシリアライズSerializing To Arrays

モデルとロード済みのリレーションを配列に変換する場合、toArrayメソッドを使います。このメソッドは再帰的に動作しますので、全属性と全リレーション（リレーションのリレーションも含む）は配列へ変換されます。To convert a model and its loaded relationships[/docs/{{version}}/eloquent-relationships] to an array, you should use the toArray method. This method is recursive, so all attributes and all relations (including the relations of relations) will be converted to arrays:

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

return $user->toArray();

モデルの属性のみを配列へ変換する場合は、attributesToArrayメソッドを使います。To convert only a model's attributes to an array, use the attributesToArray method:

$user = App\User::first();

return $user->attributesToArray();

モデルのコレクションを配列に変換することもできます。You may also convert entire collections[/docs/{{version}}/eloquent-collections] of models to arrays:

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

return $users->toArray();

JSONへのシリアライズSerializing To JSON

モデルをJSONへ変換するにはtoJsonメソッドを使います。toArrayと同様にtoJsonメソッドは再帰的に動作し、全属性と全リレーションをJSONへ変換します。さらに、PHPによりサポートされているJSONエンコーディングオプションも指定できます。To convert a model to JSON, you should use the toJson method. Like toArray, the toJson method is recursive, so all attributes and relations will be converted to JSON. You may also specify JSON encoding options supported by PHP[https://secure.php.net/manual/en/function.json-encode.php]:

$user = App\User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

もしくはモデルやコレクションが文字列へキャストされる場合、自動的にtoJsonメソッドが呼び出されます。Alternatively, you may cast a model or collection to a string, which will automatically call the toJson method on the model or collection:

$user = App\User::find(1);

return (string) $user;

文字列にキャストする場合、モデルやコレクションはJSONに変換されますので、アプリケーションのルートやコントローラから直接Eloquentオブジェクトを返すことができます。Since models and collections are converted to JSON when cast to a string, you can return Eloquent objects directly from your application's routes or controllers:

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

リレーションRelationships

EloquentモデルがJSONへ変換される場合、JSONオブジェクトへ属性として自動的にリレーションがロードされます。また、Eloquentのリレーションメソッドは「キャメルケース」で定義しますが、リレーションのJSON属性は「スネークケース」になります。When an Eloquent model is converted to JSON, its loaded relationships will automatically be included as attributes on the JSON object. Also, though Eloquent relationship methods are defined using "camel case", a relationship's JSON attribute will be "snake case".

JSONに含めない属性Hiding Attributes From JSON

モデルから変換する配列やJSONに、パスワードのような属性を含めたくない場合があります。それにはモデルの$hiddenプロパティに定義を追加してください。Sometimes you may wish to limit the attributes, such as passwords, that are included in your model's array or JSON representation. To do so, add a $hidden property to your model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 配列に含めない属性
     *
     * @var array
     */
    protected $hidden = ['password'];
}

Note: note リレーションを含めない場合は、メソッド名を指定してください。{note} When hiding relationships, use the relationship's method name.

もしくはモデルを変換後の配列やJSONに含めるべき属性のホワイトリストを定義する、visibleプロパティを使用してください。モデルが配列やJSONへ変換される場合、その他の属性はすべて、変換結果に含まれません。Alternatively, you may use the visible property to define a white-list of attributes that should be included in your model's array and JSON representation. All other attributes will be hidden when the model is converted to an array or JSON:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

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

特定のモデルインスタンスにおいて、通常は配列に含めない属性を含めたい場合は、makeVisibleメソッドを使います。このメソッドは、メソッドチェーンしやすいようにモデルインスタンスを返します。If you would like to make some typically hidden attributes visible on a given model instance, you may use the makeVisible method. The makeVisible method returns the model instance for convenient method chaining:

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

同様に、通常は含める属性を特定のインスタンスで隠したい場合は、makeHiddenメソッドを使います。Likewise, if you would like to make some typically visible attributes hidden on a given model instance, you may use the makeHidden method.

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

JSONへ値を追加Appending Values To JSON

モデルを配列やJSONへキャストするとき、データベースに対応するカラムがない属性の配列を追加する必要がある場合もときどきあります。これを行うには、最初にその値のアクセサを定義します。Occasionally, when casting models to an array or JSON, you may wish to add attributes that do not have a corresponding column in your database. To do so, first define an accessor[/docs/{{version}}/eloquent-mutators] for the value:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザーの管理者フラグを取得
     *
     * @return bool
     */
    public function getIsAdminAttribute()
    {
        return $this->attributes['admin'] === 'yes';
    }
}

アクセサができたらモデルのappendsプロパティへ属性名を追加します。アクセサが「キャメルケース」で定義されていても、属性名は通常通り「スネークケース」でアクセスされることに注目してください。After creating the accessor, add the attribute name to the appends property on the model. Note that attribute names are typically referenced in "snake case", even though the accessor is defined using "camel case":

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * モデルの配列形態に追加するアクセサ
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

appendsリストに属性を追加すれば、モデルの配列とJSON形式両方へ含まれるようになります。appends配列の属性もモデルのvisibleとhiddenの設定に従い動作します。Once the attribute has been added to the appends list, it will be included in both the model's array and JSON representations. Attributes in the appends array will also respect the visible and hidden settings configured on the model.

実行時の追加Appending At Run Time

一つのモデルインスタンスに対し、appendメソッドにより属性を追加するように指示できます。もしくは、指定したモデルに対して、追加するプロパティの配列全体をオーバーライドするために、setAppendsメソッドを使用します。You may instruct a single model instance to append attributes using the append method. Or, you may use the setAppends method to override the entire array of appended properties for a given model instance:

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

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

日付のシリアライズDate Serialization

デフォルト日付形式のカスタマイズCustomizing The Default Date Format

serializeDateメソッドをオーバーライドすることにより、デフォルトの日付位形式をカスタマイズできます。You may customize the default serialization format by overriding the serializeDate method:

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

属性ごとに日付形式をカスタマイズCustomizing The Date Format Per Attribute

キャスト宣言で日付形式を指定することにより、Eloquent日付属性ごとにシリアライズ形式をカスタマイズできます。You may customize the serialization format of individual Eloquent date attributes by specifying the date format in the cast declaration[/docs/{{version}}/eloquent-mutators#attribute-casting]:

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