Laravel 10.x Eloquent：ミューテタ／キャスト

イントロダクションIntroduction

アクセサ、ミューテタ、および属性キャストを使用すると、Eloquentモデルインスタンスで属性値を取得または設定するときに、それらの属性値を変換できます。たとえば、Laravel暗号化を使用して、データベースに保存されている値を暗号化し、Eloquentモデル上でそれにアクセスしたときに属性を自動的に復号できます。他に、Eloquentモデルを介してアクセスするときに、データベースに格納されているJSON文字列を配列に変換することもできます。Accessors, mutators, and attribute casting allow you to transform Eloquent attribute values when you retrieve or set them on model instances. For example, you may want to use the Laravel encrypter[/docs/{{version}}/encryption] to encrypt a value while it is stored in the database, and then automatically decrypt the attribute when you access it on an Eloquent model. Or, you may want to convert a JSON string that is stored in your database to an array when it is accessed via your Eloquent model.

アクセサ／ミューテタAccessors and Mutators

アクセサの定義Defining an Accessor

アクセサは、Eloquentの属性値にアクセスが合った時に、その値を変換するものです。アクセサを定義するには、アクセス可能な属性を表すprotectedなメソッドをモデル上に作成します。このメソッド名は、裏に存在するモデル属性やデータベースカラムの「キャメルケース」表現に対応させる必要があります。An accessor transforms an Eloquent attribute value when it is accessed. To define an accessor, create a protected method on your model to represent the accessible attribute. This method name should correspond to the "camel case" representation of the true underlying model attribute / database column when applicable.

この例では、first_name属性に対するアクセサを定義します。このアクセサは、first_name属性の値を取得しようとしたときに、Eloquentから自動的に呼び出されます。すべての属性アクセサ/ミューテタメソッドは、戻り値のタイプヒントをIlluminate\Database\Eloquent\Casts\Attributeで宣言する必要があります。In this example, we'll define an accessor for the first_name attribute. The accessor will automatically be called by Eloquent when attempting to retrieve the value of the first_name attribute. All attribute accessor / mutator methods must declare a return type-hint of Illuminate\Database\Eloquent\Casts\Attribute:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * ユーザーの名前の取得
     */
    protected function firstName(): Attribute
    {
        return Attribute::make(
            get: fn (string $value) => ucfirst($value),
        );
    }
}

すべてのアクセサメソッドはAttributeインスタンスを返します。このインスタンスは、属性にアクセスする方法と、オプションとして変異させる方法を定義します。この例では、属性にアクセスする方法のみを定義しています。そのために、Attributeクラスのコンストラクタにget引数を与えます。All accessor methods return an Attribute instance which defines how the attribute will be accessed and, optionally, mutated. In this example, we are only defining how the attribute will be accessed. To do so, we supply the get argument to the Attribute class constructor.

ご覧のとおり、カラムの元の値がアクセサに渡され、値を操作でき、結果値を返します。アクセサの値へアクセスするには、モデルインスタンスのfirst_name属性にアクセスするだけです。As you can see, the original value of the column is passed to the accessor, allowing you to manipulate and return the value. To access the value of the accessor, you may simply access the first_name attribute on a model instance:

use App\Models\User;

$user = User::find(1);

$firstName = $user->first_name;

lightbulb Note: こうした計算値をモデルの配列／JSON表現に追加したい場合は、手作業で追加する必要があります。[!NOTE]
If you would like these computed values to be added to the array / JSON representations of your model, you will need to append them[/docs/{{version}}/eloquent-serialization#appending-values-to-json].

複数の属性からの値オブジェクト構築Building Value Objects From Multiple Attributes

複数のモデル属性を一つの「値オブジェクト」へアクセサで、変換する必要がある場合も起きるでしょう。そのため、getクロージャの第２引数は$attributesであり、自動的にこのクロージャに用意され、モデルの現在の属性をすべて配列で持っています。Sometimes your accessor may need to transform multiple model attributes into a single "value object". To do so, your get closure may accept a second argument of $attributes, which will be automatically supplied to the closure and will contain an array of all of the model's current attributes:

use App\Support\Address;
use Illuminate\Database\Eloquent\Casts\Attribute;

/**
 * ユーザーの住所を操作
 */
protected function address(): Attribute
{
    return Attribute::make(
        get: fn (mixed $value, array $attributes) => new Address(
            $attributes['address_line_one'],
            $attributes['address_line_two'],
        ),
    );
}

アクセサのキャッシュAccessor Caching

アクセサから値オブジェクトを返すとき、値オブジェクトに加えられたすべての変更は、モデルが保存される前に自動的にモデルに同期して戻されます。これはEloquentがアクセサから返したインスタンスを保持し、アクセサが呼び出されるたびに同じインスタンスを返すことができるためです。When returning value objects from accessors, any changes made to the value object will automatically be synced back to the model before the model is saved. This is possible because Eloquent retains instances returned by accessors so it can return the same instance each time the accessor is invoked:

use App\Models\User;

$user = User::find(1);

$user->address->lineOne = 'Updated Address Line 1 Value';
$user->address->lineTwo = 'Updated Address Line 2 Value';

$user->save();

しかし、文字列やブーリアンなどのプリミティブな値については、特に計算量が多い場合、キャッシュを有効にしたい場合が起きます。その場合は、アクセサを定義するときに、shouldCacheメソッドを呼び出してください。However, you may sometimes wish to enable caching for primitive values like strings and booleans, particularly if they are computationally intensive. To accomplish this, you may invoke the shouldCache method when defining your accessor:

protected function hash(): Attribute
{
    return Attribute::make(
        get: fn (string $value) => bcrypt(gzuncompress($value)),
    )->shouldCache();
}

属性のオブジェクトキャッシュ動作を無効にしたい場合は、属性の定義時にwithoutObjectCachingメソッドを呼び出してください。If you would like to disable the object caching behavior of attributes, you may invoke the withoutObjectCaching method when defining the attribute:

/**
 * ユーザーの住所を操作
 */
protected function address(): Attribute
{
    return Attribute::make(
        get: fn (mixed $value, array $attributes) => new Address(
            $attributes['address_line_one'],
            $attributes['address_line_two'],
        ),
    )->withoutObjectCaching();
}

ミューテタの定義Defining a Mutator

ミューテタはEloquentの属性値を設定するときに、その値を変換するものです。ミューテタを定義するには、属性を定義するときに set という引数を指定します。ここでは、first_name属性に対してミューテタを定義してみましょう。このミューテタは、モデルのfirst_name属性の値を設定しようとすると、自動的に呼び出されます。A mutator transforms an Eloquent attribute value when it is set. To define a mutator, you may provide the set argument when defining your attribute. Let's define a mutator for the first_name attribute. This mutator will be automatically called when we attempt to set the value of the first_name attribute on the model:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * ユーザーの名を操作
     */
    protected function firstName(): Attribute
    {
        return Attribute::make(
            get: fn (string $value) => ucfirst($value),
            set: fn (string $value) => strtolower($value),
        );
    }
}

ミューテタクロージャは、属性に設定しようとする値を受け取り、その値を操作して、操作した値を返します。このミューテタを使うには、Eloquentモデルにfirst_name属性をセットするだけでよいのです。The mutator closure will receive the value that is being set on the attribute, allowing you to manipulate the value and return the manipulated value. To use our mutator, we only need to set the first_name attribute on an Eloquent model:

use App\Models\User;

$user = User::find(1);

$user->first_name = 'Sally';

この例では、setコールバックがSallyという値で呼び出されます。ミューテタはstrtolower関数を名前に適用し、その結果をモデルの内部配列$attributesへセットします。In this example, the set callback will be called with the value Sally. The mutator will then apply the strtolower function to the name and set its resulting value in the model's internal $attributes array.

複数属性のミュートMutating Multiple Attributes

時には、ミューテーターは裏のモデルへ複数の属性をセットする必要があるかもしれません。その場合は、setクロージャから配列を返します。配列の各キーは、モデルと関連付けられた属性やデータベースカラムに対応している必要があります。Sometimes your mutator may need to set multiple attributes on the underlying model. To do so, you may return an array from the set closure. Each key in the array should correspond with an underlying attribute / database column associated with the model:

use App\Support\Address;
use Illuminate\Database\Eloquent\Casts\Attribute;

/**
 * ユーザーの住所を操作
 */
protected function address(): Attribute
{
    return Attribute::make(
        get: fn (mixed $value, array $attributes) => new Address(
            $attributes['address_line_one'],
            $attributes['address_line_two'],
        ),
        set: fn (Address $value) => [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ],
    );
}

属性のキャストAttribute Casting

属性キャストは、モデルで追加のメソッドを定義することなく、アクセサやミューテタと同様の機能を提供します。定義する代わりに、モデルの$castsプロパティにより属性を一般的なデータ型に変換する便利な方法を提供します。Attribute casting provides functionality similar to accessors and mutators without requiring you to define any additional methods on your model. Instead, your model's $casts property provides a convenient method of converting attributes to common data types.

$castsプロパティは、キーがキャストする属性の名前であり、値がそのカラムをキャストするタイプである配列である必要があります。サポートしているキャストタイプは以下のとおりです。The $casts property should be an array where the key is the name of the attribute being cast and the value is the type you wish to cast the column to. The supported cast types are:

属性のキャストをデモンストレートするため、データベースに整数(0または1)として格納しているis_admin属性をブール値にキャストしてみましょう。To demonstrate attribute casting, let's cast the is_admin attribute, which is stored in our database as an integer (0 or 1) to a boolean value:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * キャストする必要のある属性
     *
     * @var array
     */
    protected $casts = [
        'is_admin' => 'boolean',
    ];
}

キャストを定義した後、基になる値が整数としてデータベースに格納されていても、アクセス時is_admin属性は常にブール値にキャストされます。After defining the cast, the is_admin attribute will always be cast to a boolean when you access it, even if the underlying value is stored in the database as an integer:

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

if ($user->is_admin) {
    // ...
}

実行時に新しく一時的なキャストを追加する必要がある場合は、mergeCastsメソッドを使用します。こうしたキャストの定義は、モデルで既に定義しているキャストのいずれかに追加されます。If you need to add a new, temporary cast at runtime, you may use the mergeCasts method. These cast definitions will be added to any of the casts already defined on the model:

$user->mergeCasts([
    'is_admin' => 'integer',
    'options' => 'object',
]);

warning Warning! nullである属性はキャストしません。また、リレーションと同じ名前のキャスト（または属性）を定義したり、モデルの主キーにキャストを割り当てたりは、決してしないでください。[!WARNING]
Attributes that are null will not be cast. In addition, you should never define a cast (or an attribute) that has the same name as a relationship or assign a cast to the model's primary key.

StringableのキャストStringable Casting

モデルの属性をfluentのIlluminate\Support\Stringableオブジェクトへキャストするには、Illuminate\Database\Eloquent\Casts\AsStringableキャストクラスが使用できます。You may use the Illuminate\Database\Eloquent\Casts\AsStringable cast class to cast a model attribute to a fluent Illuminate\Support\Stringable object[/docs/{{version}}/strings#fluent-strings-method-list]:

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * キャストする必要のある属性
     *
     * @var array
     */
    protected $casts = [
        'directory' => AsStringable::class,
    ];
}

配列とJSONのキャストArray and JSON Casting

arrayキャストは、シリアル化されたJSONとして保存されているカラムを操作するときに特に役立ちます。たとえば、データベースにシリアル化されたJSONを含むJSONまたはTEXTフィールドタイプがある場合、その属性へarrayキャストを追加すると、Eloquentモデル上でアクセス時に、属性がPHP配列へ自動的に逆シリアル化されます。The array cast is particularly useful when working with columns that are stored as serialized JSON. For example, if your database has a JSON or TEXT field type that contains serialized JSON, adding the array cast to that attribute will automatically deserialize the attribute to a PHP array when you access it on your Eloquent model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * キャストする必要のある属性
     *
     * @var array
     */
    protected $casts = [
        'options' => 'array',
    ];
}

このキャストを定義すると、options属性にアクセスでき、JSONからPHP配列に自動的に逆シリアル化されます。options属性の値を設定すると、指定する配列が自動的にシリアル化されてJSONに戻されて保存されます。Once the cast is defined, you may access the options attribute and it will automatically be deserialized from JSON into a PHP array. When you set the value of the options attribute, the given array will automatically be serialized back into JSON for storage:

use App\Models\User;

$user = User::find(1);

$options = $user->options;

$options['key'] = 'value';

$user->options = $options;

$user->save();

より簡潔な構文でJSON属性の単一フィールドを更新するには、その属性を複数代入可能にし、updateメソッドを呼び出すときに、->演算子を使用してください。To update a single field of a JSON attribute with a more terse syntax, you may make the attribute mass assignable[/docs/{{version}}/eloquent#mass-assignment-json-columns] and use the -> operator when calling the update method:

$user = User::find(1);

$user->update(['options->key' => 'value']);

配列オブジェクトとコレクションのキャストArray Object and Collection Casting

多くのアプリケーションには標準のarrayキャストで十分ですが、いくつかの欠点を持ちます。arrayキャストはプリミティブ型を返すので、配列のオフセットを直接変更することはできません。たとえば、次のコードはPHPエラーを起こします。Although the standard array cast is sufficient for many applications, it does have some disadvantages. Since the array cast returns a primitive type, it is not possible to mutate an offset of the array directly. For example, the following code will trigger a PHP error:

$user = User::find(1);

$user->options['key'] = $value;

これを解決するために、Laravelは、JSON属性をArrayObjectクラスにキャストするasArrayObjectキャストを提供します。この機能はLaravelのカスタムキャストの実装を使用しており、Laravelがインテリジェントにキャッシュし、PHPエラーを引き起こすことなく、個々のオフセットを変更できるように、ミューテートしたオブジェクトを変換することができます。AsArrayObject`のキャストを使用するには、単純に属性に割り当てるだけです。To solve this, Laravel offers an AsArrayObject cast that casts your JSON attribute to an ArrayObject[https://www.php.net/manual/en/class.arrayobject.php] class. This feature is implemented using Laravel's custom cast[#custom-casts] implementation, which allows Laravel to intelligently cache and transform the mutated object such that individual offsets may be modified without triggering a PHP error. To use the AsArrayObject cast, simply assign it to an attribute:

use Illuminate\Database\Eloquent\Casts\AsArrayObject;

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'options' => AsArrayObject::class,
];

同様に、LaravelはJSON属性をLaravelコレクションへキャストするASCollectionキャストを提供していますSimilarly, Laravel offers an AsCollection cast that casts your JSON attribute to a Laravel Collection[/docs/{{version}}/collections] instance:

use Illuminate\Database\Eloquent\Casts\AsCollection;

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'options' => AsCollection::class,
];

AsCollectionキャストでLaravel基本コレクションクラスの代わりに、カスタムコレクションクラスをインスタンス化したい場合は、キャストの引数としてコレクションクラス名を指定してください。If you would like the AsCollection cast to instantiate a custom collection class instead of Laravel's base collection class, you may provide the collection class name as a cast argument:

use App\Collections\OptionCollection;
use Illuminate\Database\Eloquent\Casts\AsCollection;

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'options' => AsCollection::class.':'.OptionCollection::class,
];

日付のキャストDate Casting

デフォルトでは、Eloquentはcreated_atカラムとupdated_atカラムをCarbonのインスタンスへキャストします。これによりPHPのDateTimeクラスを拡張した、多くの便利なメソッドが提供されます。モデルの$castsプロパティ配列内で日付キャストを追加定義すれば、他の日付属性をキャストできます。通常、日付はdatetimeかimmutable_datetimeキャストタイプを使用してキャストする必要があります。By default, Eloquent will cast the created_at and updated_at columns to instances of Carbon[https://github.com/briannesbitt/Carbon], which extends the PHP DateTime class and provides an assortment of helpful methods. You may cast additional date attributes by defining additional date casts within your model's $casts property array. Typically, dates should be cast using the datetime or immutable_datetime cast types.

dateまたはdatetimeキャストを定義するときに、日付の形式を指定することもできます。この形式は、モデルが配列またはJSONにシリアル化される場合に使用されます。When defining a date or datetime cast, you may also specify the date's format. This format will be used when the model is serialized to an array or JSON[/docs/{{version}}/eloquent-serialization]:

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'created_at' => 'datetime:Y-m-d',
];

カラムが日付へキャストされる場合、対応するモデル属性の値として、UNIXのタイムスタンプ、日付文字列（Y-m-d）、日付時間文字列、またはDateTime／Carbonインスタンスを設定することができます。日付の値は正しく変換され、データベースへ保存されます。When a column is cast as a date, you may set the corresponding model attribute value to a UNIX timestamp, date string (Y-m-d), date-time string, or a DateTime / Carbon instance. The date's value will be correctly converted and stored in your database.

モデルにserializeDateメソッドを定義することで、モデルのすべての日付のデフォルトのシリアル化形式をカスタマイズできます。この方法は、データベースへ保存するために日付をフォーマットする方法には影響しません。You may customize the default serialization format for all of your model's dates by defining a serializeDate method on your model. This method does not affect how your dates are formatted for storage in the database:

/**
 * 配列/JSONシリアル化の日付を準備
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

データベース内にモデルの日付を実際に保存するときに使用する形式を指定するには、モデルに$dateFormatプロパティを定義する必要があります。To specify the format that should be used when actually storing a model's dates within your database, you should define a $dateFormat property on your model:

/**
 * モデルの日付カラムのストレージ形式
 *
 * @var string
 */
protected $dateFormat = 'U';

日付のキャストとシリアライズ、タイムゾーンDate Casting, Serialization, and Timezones

dateとdatetimeのキャストはデフォルトで、アプリケーションのtimezone設定オプションで指定されているタイムゾーンに関わらず、日付をUTC ISO-8601の日付文字列（YYYY-MM-DDTHH:MM:SS.uuuuuuZ）にシリアライズします。アプリケーションのtimezone設定オプションをデフォルトのUTCから変更せずに、常にこのシリアライズ形式を使用し、アプリケーションの日付をUTCタイムゾーンで保存することを強く推奨します。アプリケーション全体でUTCタイムゾーンを一貫して使用することで、PHPやJavaScriptで書かれた他の日付操作ライブラリとの相互運用性を最大限に高められます。By default, the date and datetime casts will serialize dates to a UTC ISO-8601 date string (YYYY-MM-DDTHH:MM:SS.uuuuuuZ), regardless of the timezone specified in your application's timezone configuration option. You are strongly encouraged to always use this serialization format, as well as to store your application's dates in the UTC timezone by not changing your application's timezone configuration option from its default UTC value. Consistently using the UTC timezone throughout your application will provide the maximum level of interoperability with other date manipulation libraries written in PHP and JavaScript.

datetime:Y-m-d H:i:sのようなカスタムフォーマットをdateやdatetimeキャストで適用する場合は、日付のシリアライズの際に、Carbonインスタンスの内部タイムゾーンが使用されます。一般的には、アプリケーションのtimezone設定オプションで指定したタイムゾーンを使用します。If a custom format is applied to the date or datetime cast, such as datetime:Y-m-d H:i:s, the inner timezone of the Carbon instance will be used during date serialization. Typically, this will be the timezone specified in your application's timezone configuration option.

EnumキャストEnum Casting

Eloquentは、属性値をPHPのEnum にキャストすることも可能です。これを実現するには、モデルの$castsプロパティ配列にキャストしたい属性と列挙型を指定します。Eloquent also allows you to cast your attribute values to PHP Enums[https://www.php.net/manual/en/language.enumerations.backed.php]. To accomplish this, you may specify the attribute and enum you wish to cast in your model's $casts property array:

use App\Enums\ServerStatus;

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'status' => ServerStatus::class,
];

モデルにキャストを定義すると、指定した属性を操作する際に、自動的にenumへキャストしたり、enumからキャストされたりするようになります。Once you have defined the cast on your model, the specified attribute will be automatically cast to and from an enum when you interact with the attribute:

if ($server->status == ServerStatus::Provisioned) {
    $server->status = ServerStatus::Ready;

    $server->save();
}

Enum配列のキャストCasting Arrays of Enums

時に、１つのカラムにenum値の配列を格納するモデルが必要になることがあります。これを実現するには、Laravelが提供するAsEnumArrayObject、またはAsEnumCollectionキャストを利用します。Sometimes you may need your model to store an array of enum values within a single column. To accomplish this, you may utilize the AsEnumArrayObject or AsEnumCollection casts provided by Laravel:

use App\Enums\ServerStatus;
use Illuminate\Database\Eloquent\Casts\AsEnumCollection;

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'statuses' => AsEnumCollection::class.':'.ServerStatus::class,
];

暗号化キャストEncrypted Casting

encryptedキャストは、Laravelに組み込まれた暗号化機能を使って、モデルの属性値を暗号化します。さらに、encrypted:array、encrypted:collection、encrypted:object、AsEncryptedArrayObject、AsEncryptedCollectionのキャストは、暗号化されていないものと同様の動作をしますが、ご期待通りにデータベースに保存される際に、基本的な値を暗号化します。The encrypted cast will encrypt a model's attribute value using Laravel's built-in encryption[/docs/{{version}}/encryption] features. In addition, the encrypted:array, encrypted:collection, encrypted:object, AsEncryptedArrayObject, and AsEncryptedCollection casts work like their unencrypted counterparts; however, as you might expect, the underlying value is encrypted when stored in your database.

暗号化したテキストの最終的な長さは予測できず、プレーンテキストのものよりも長くなるので、関連するデータベースのカラムが TEXT 型以上であることを確認してください。さらに、値はデータベース内で暗号化されているので、暗号化された属性値を問い合わせたり検索したりすることはできません。As the final length of the encrypted text is not predictable and is longer than its plain text counterpart, make sure the associated database column is of TEXT type or larger. In addition, since the values are encrypted in the database, you will not be able to query or search encrypted attribute values.

キーの変更Key Rotation

ご存知のように、Laravelはアプリケーションのapp設定ファイルで指定したkey設定値を使い、文字列を暗号化します。通常、この値は環境変数APP_KEYの値です。もし、アプリケーションの暗号化キーを変更する必要がある場合は、新しいキーを使い、暗号化した属性を手作業で再暗号化する必要があります。As you may know, Laravel encrypts strings using the key configuration value specified in your application's app configuration file. Typically, this value corresponds to the value of the APP_KEY environment variable. If you need to rotate your application's encryption key, you will need to manually re-encrypt your encrypted attributes using the new key.

クエリ時のキャストQuery Time Casting

テーブルから元の値でセレクトするときなど、クエリの実行中にキャストを適用する必要が起きる場合があります。たとえば、次のクエリを考えてみましょう。Sometimes you may need to apply casts while executing a query, such as when selecting a raw value from a table. For example, consider the following query:

use App\Models\Post;
use App\Models\User;

$users = User::select([
    'users.*',
    'last_posted_at' => Post::selectRaw('MAX(created_at)')
            ->whereColumn('user_id', 'users.id')
])->get();

このクエリ結果のlast_posted_at属性は単純な文字列になります。クエリを実行するときに、この属性に「datetime」キャストを適用できれば素晴らしいと思うでしょう。幸運なことに、withCastsメソッドを使用してこれができます。The last_posted_at attribute on the results of this query will be a simple string. It would be wonderful if we could apply a datetime cast to this attribute when executing the query. Thankfully, we may accomplish this using the withCasts method:

$users = User::select([
    'users.*',
    'last_posted_at' => Post::selectRaw('MAX(created_at)')
            ->whereColumn('user_id', 'users.id')
])->withCasts([
    'last_posted_at' => 'datetime'
])->get();

カスタムキャストCustom Casts

Laravelには便利で様々な組み込みキャストタイプがあります。それでも、独自のキャストタイプを定義する必要がある場合もあるでしょう。キャストを作成するには、make:cast Artisanコマンドを実行します。新しいキャストクラスは、app/Castsディレクトリに配置されます。Laravel has a variety of built-in, helpful cast types; however, you may occasionally need to define your own cast types. To create a cast, execute the make:cast Artisan command. The new cast class will be placed in your app/Casts directory:

php artisan make:cast Json

すべてのカスタムキャストクラスは、CastsAttributesインターフェイスを実装します。このインターフェイスを実装するクラスは、getとsetメソッドを定義しなければなりません。getメソッドはデータベースから素の値をキャスト値に変換する役割を果たし、setメソッドはキャスト値をデータベースへ保存できる素の値に変換する必要があります。例として、組み込みのキャスト型であるjsonをカスタムキャスト型として再実装してみます。All custom cast classes implement the CastsAttributes interface. Classes that implement this interface must define a get and set method. The get method is responsible for transforming a raw value from the database into a cast value, while the set method should transform a cast value into a raw value that can be stored in the database. As an example, we will re-implement the built-in json cast type as a custom cast type:

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;

class Json implements CastsAttributes
{
    /**
     * 指定値をキャスト
     *
     * @param  array<string, mixed>  $attributes
     * @return array<string, mixed>
     */
    public function get(Model $model, string $key, mixed $value, array $attributes): array
    {
        return json_decode($value, true);
    }

    /**
     * 指定値をストレージ用に準備
     *
     * @param  array<string, mixed>  $attributes
     */
    public function set(Model $model, string $key, mixed $value, array $attributes): string
    {
        return json_encode($value);
    }
}

カスタムキャストタイプを定義したら、そのクラス名をモデル属性へ指定できます。Once you have defined a custom cast type, you may attach it to a model attribute using its class name:

<?php

namespace App\Models;

use App\Casts\Json;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * キャストする必要のある属性
     *
     * @var array
     */
    protected $casts = [
        'options' => Json::class,
    ];
}

値オブジェクトのキャストValue Object Casting

値をプリミティブ型にキャストすることに限定されません。オブジェクトへ値をキャストすることもできます。オブジェクトへ値をキャストするカスタムキャストの定義は、プリミティブ型へのキャストと非常によく似ています。ただし、setメソッドは、モデルに素の保存可能な値を設定するために使用するキー／値のペアの配列を返す必要があります。You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, the set method should return an array of key / value pairs that will be used to set raw, storable values on the model.

例として、複数のモデル値を単一のAddress値オブジェクトにキャストするカスタムキャストクラスを定義します。Address値には、lineOneとlineTwoの２つのパブリックプロパティがあると想定します。As an example, we will define a custom cast class that casts multiple model values into a single Address value object. We will assume the Address value has two public properties: lineOne and lineTwo:

<?php

namespace App\Casts;

use App\ValueObjects\Address as AddressValueObject;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Illuminate\Database\Eloquent\Model;
use InvalidArgumentException;

class Address implements CastsAttributes
{
    /**
     * 指定値をキャスト
     *
     * @param  array<string, mixed>  $attributes
     */
    public function get(Model $model, string $key, mixed $value, array $attributes): AddressValueObject
    {
        return new AddressValueObject(
            $attributes['address_line_one'],
            $attributes['address_line_two']
        );
    }

    /**
     * 指定値をストレージ用に準備
     *
     * @param  array<string, mixed>  $attributes
     * @return array<string, string>
     */
    public function set(Model $model, string $key, mixed $value, array $attributes): array
    {
        if (! $value instanceof AddressValueObject) {
            throw new InvalidArgumentException('The given value is not an Address instance.');
        }

        return [
            'address_line_one' => $value->lineOne,
            'address_line_two' => $value->lineTwo,
        ];
    }
}

値オブジェクトにキャストする場合、値オブジェクトに加えられた変更は、モデルが保存される前に自動的にモデルに同期されます。When casting to value objects, any changes made to the value object will automatically be synced back to the model before the model is saved:

use App\Models\User;

$user = User::find(1);

$user->address->lineOne = 'Updated Address Value';

$user->save();

lightbulb Note: 値オブジェクトを含むEloquentモデルをJSONまたは配列にシリアル化する場合は、値オブジェクトにIlluminate\Contracts\Support\ArrayableおよびJsonSerializableインターフェイスを実装する必要があります。[!NOTE]
If you plan to serialize your Eloquent models containing value objects to JSON or arrays, you should implement the Illuminate\Contracts\Support\Arrayable and JsonSerializable interfaces on the value object.

値オブジェクトのキャッシュValue Object Caching

値オブジェクトへキャストする属性を解決する場合、Eloquentはそれらをキャッシュします。そのため、属性へ再度アクセスすると、同じオブジェクトのインスタンスを返します。When attributes that are cast to value objects are resolved, they are cached by Eloquent. Therefore, the same object instance will be returned if the attribute is accessed again.

カスタムキャストクラスのオブジェクトキャッシュ動作を無効にしたい場合は、カスタムキャストクラスでpublicのwithoutObjectCachingプロパティを宣言してください。If you would like to disable the object caching behavior of custom cast classes, you may declare a public withoutObjectCaching property on your custom cast class:

class Address implements CastsAttributes
{
    public bool $withoutObjectCaching = true;

    // ...
}

配列／JSONのシリアル化Array / JSON Serialization

EloquentモデルをtoArrayおよびtoJsonメソッドを使用して配列やJSONへ変換する場合、カスタムキャスト値オブジェクトは通常、Illuminate\Contracts\Support\ArrayableおよびJsonSerializableインターフェイスを実装している限りシリアル化されます。しかし、サードパーティライブラリによって提供される値オブジェクトを使用する場合、これらのインターフェイスをオブジェクトに追加できない場合があります。When an Eloquent model is converted to an array or JSON using the toArray and toJson methods, your custom cast value objects will typically be serialized as well as long as they implement the Illuminate\Contracts\Support\Arrayable and JsonSerializable interfaces. However, when using value objects provided by third-party libraries, you may not have the ability to add these interfaces to the object.

したがって、カスタムキャストクラスが値オブジェクトのシリアル化を担当するように指定できます。そのためには、カスタムクラスキャストでIlluminate\Contracts\Database\Eloquent\SerializesCastableAttributesインターフェイスを実装する必要があります。このインターフェイスは、クラスに「serialize」メソッドが含まれている必要があることを示しています。このメソッドは、値オブジェクトのシリアル化された形式を返す必要があります。Therefore, you may specify that your custom cast class will be responsible for serializing the value object. To do so, your custom cast class should implement the Illuminate\Contracts\Database\Eloquent\SerializesCastableAttributes interface. This interface states that your class should contain a serialize method which should return the serialized form of your value object:

/**
 * 値をシリアル化した表現の取得
 *
 * @param  array<string, mixed>  $attributes
 */
public function serialize(Model $model, string $key, mixed $value, array $attributes): string
{
    return (string) $value;
}

インバウンドのキャストInbound Casting

場合により、モデルに値を設定するときのみ変換し、モデルから属性を取得するときには何も操作を行わないカスタムキャストクラスを記述する必要があるかもしれません。Occasionally, you may need to write a custom cast class that only transforms values that are being set on the model and does not perform any operations when attributes are being retrieved from the model.

受け取り専用のカスタムキャストは、CastsInboundAttributesインターフェイスを実装し、setメソッドのみを定義する必要があります。Artisanのmake:castコマンドに--inboundオプションを付けて実行すると、受け取り専用のキャストクラスを生成できます。Inbound only custom casts should implement the CastsInboundAttributes interface, which only requires a set method to be defined. The make:cast Artisan command may be invoked with the --inbound option to generate an inbound only cast class:

php artisan make:cast Hash --inbound

受け取り専用キャストの典型的な例は、「ハッシュ」キャストです。たとえば、あるアルゴリズムで受け取った値をハッシュするキャストを定義できます。A classic example of an inbound only cast is a "hashing" cast. For example, we may define a cast that hashes inbound values via a given algorithm:

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;
use Illuminate\Database\Eloquent\Model;

class Hash implements CastsInboundAttributes
{
    /**
     * 新しいキャストクラスインスタンスの生成
     */
    public function __construct(
        protected string|null $algorithm = null,
    ) {}

    /**
     * 指定値をストレージ用に準備
     *
     * @param  array<string, mixed>  $attributes
     */
    public function set(Model $model, string $key, mixed $value, array $attributes): string
    {
        return is_null($this->algorithm)
                    ? bcrypt($value)
                    : hash($this->algorithm, $value);
    }
}

キャストのパラメータCast Parameters

カスタムキャストをモデルへ指定する場合、:文字を使用してクラス名から分離し、複数のパラメータをコンマで区切ることでキャストパラメータを指定できます。パラメータは、キャストクラスのコンストラクタへ渡されます。When attaching a custom cast to a model, cast parameters may be specified by separating them from the class name using a : character and comma-delimiting multiple parameters. The parameters will be passed to the constructor of the cast class:

/**
 * キャストする属性
 *
 * @var array
 */
protected $casts = [
    'secret' => Hash::class.':sha256',
];

CastablesCastables

アプリケーションの値オブジェクトが独自のカスタムキャストクラスを定義できるようにすることができます。カスタムキャストクラスをモデルにアタッチする代わりに、Illuminate\Contracts\Database\Eloquent\Castableインターフェイスを実装する値オブジェクトクラスをアタッチすることもできます。You may want to allow your application's value objects to define their own custom cast classes. Instead of attaching the custom cast class to your model, you may alternatively attach a value object class that implements the Illuminate\Contracts\Database\Eloquent\Castable interface:

use App\ValueObjects\Address;

protected $casts = [
    'address' => Address::class,
];

Castableインターフェイスを実装するオブジェクトは、Castableクラスにキャストする／される責務を受け持つ、カスタムキャスタークラスのクラス名を返すcastUsingメソッドを定義する必要があります。Objects that implement the Castable interface must define a castUsing method that returns the class name of the custom caster class that is responsible for casting to and from the Castable class:

<?php

namespace App\ValueObjects;

use Illuminate\Contracts\Database\Eloquent\Castable;
use App\Casts\Address as AddressCast;

class Address implements Castable
{
    /**
     * このキャストターゲットにキャストする／されるときに使用するキャスタークラスの名前を取得
     *
     * @param  array<string, mixed>  $arguments
     */
    public static function castUsing(array $arguments): string
    {
        return AddressCast::class;
    }
}

Castableクラスを使用する場合でも、$casts定義に引数を指定できます。引数はcastUsingメソッドに渡されます。When using Castable classes, you may still provide arguments in the $casts definition. The arguments will be passed to the castUsing method:

use App\ValueObjects\Address;

protected $casts = [
    'address' => Address::class.':argument',
];

Castableと匿名キャストクラスCastables & Anonymous Cast Classes

"Castable"をPHPの匿名クラスと組み合わせることで、値オブジェクトとそのキャストロジックを単一のCastableオブジェクトとして定義できます。これを実現するには、値オブジェクトのcastUsingメソッドから匿名クラスを返します。匿名クラスはCastsAttributesインターフェイスを実装する必要があります。By combining "castables" with PHP's anonymous classes[https://www.php.net/manual/en/language.oop5.anonymous.php], you may define a value object and its casting logic as a single castable object. To accomplish this, return an anonymous class from your value object's castUsing method. The anonymous class should implement the CastsAttributes interface:

<?php

namespace App\ValueObjects;

use Illuminate\Contracts\Database\Eloquent\Castable;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class Address implements Castable
{
    // ...

    /**
     * このキャストターゲットにキャストする／されるときに使用するキャスタークラスの名前を取得
     *
     * @param  array<string, mixed>  $arguments
     */
    public static function castUsing(array $arguments): CastsAttributes
    {
        return new class implements CastsAttributes
        {
            public function get(Model $model, string $key, mixed $value, array $attributes): Address
            {
                return new Address(
                    $attributes['address_line_one'],
                    $attributes['address_line_two']
                );
            }

            public function set(Model $model, string $key, mixed $value, array $attributes): array
            {
                return [
                    'address_line_one' => $value->lineOne,
                    'address_line_two' => $value->lineTwo,
                ];
            }
        };
    }
}