イントロダクションIntroduction
アクセサとミューテタはモデルの取得や値を設定するときに、Eloquent属性のフォーマットを可能にします。たとえばLaravelの暗号化を使いデータベース保存時に値を暗号化し、Eloquentモデルでアクセスする時には自動的にその属性を復元するように設定できます。Accessors and mutators allow you to format 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.
カスタムのアクセサやミューテタに加え、Eloquentは日付フールドを自動的にCarbonインスタンスにキャストしますし、テキストフィールドをJSONにキャストすることもできます。In addition to custom accessors and mutators, Eloquent can also automatically cast date fields to Carbon[https://github.com/briannesbitt/Carbon] instances or even cast text fields to JSON[#attribute-casting].
アクセサとミューテタAccessors & Mutators
アクセサの定義Defining An Accessor
アクセサを定義するには、アクセスしたいカラム名が「studlyケース（Upper Camel Case）」でFooの場合、getFooAttributeメソッドをモデルに作成します。以下の例では、first_name属性のアクセサを定義しています。first_name属性の値にアクセスが起きると、Eloquentは自動的にこのアクセサを呼び出します。To define an accessor, create a getFooAttribute method on your model where Foo is the "studly" cased name of the column you wish to access. 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:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* ユーザーのファーストネームを取得
*
* @param string $value
* @return string
*/
public function getFirstNameAttribute($value)
{
return ucfirst($value);
}
}
ご覧の通り、アクセサにはそのカラムのオリジナルの値が渡されますので、それを加工し値を返します。アクセサの値にアクセスするには、モデルインスタンスの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 access the first_name attribute on a model instance:
$user = App\User::find(1);
$firstName = $user->first_name;
既存の属性を元に算出した、新しい値をアクセサを使用し返すことも可能です。You may also use accessors to return new, computed values from existing attributes:
/**
* ユーザーのフルネーム取得
*
* @return string
*/
public function getFullNameAttribute()
{
return "{$this->first_name} {$this->last_name}";
}
">Tip!! これらの計算済みの値をモデルのarray／JSON表現に追加したい場合は、プロパティに追加する必要があります。{tip} If you would like these computed values to be added to the array / JSON representations of your model, you will need to append them[https://laravel.com/docs/{{version}}/eloquent-serialization#appending-values-to-json].
ミューテタの定義Defining A Mutator
ミューテタを定義するにはアクセスしたいカラム名がFooの場合、モデルに「ローワーキャメルケース」でsetFooAttributeメソッドを作成します。今回もfirst_name属性を取り上げ、ミューテタを定義しましょう。このミューテタはモデルのfirst_name属性へ値を設定する時に自動的に呼びだされます。To define a mutator, define a setFooAttribute method on your model where Foo is the "studly" cased name of the column you wish to access. So, again, 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;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* ユーザーのファーストネームを設定
*
* @param string $value
* @return void
*/
public function setFirstNameAttribute($value)
{
$this->attributes['first_name'] = strtolower($value);
}
}
ミューテタは属性に設定しようとしている値を受け取りますのでこれを加工し、Eloquentモデルの$attributes内部プロパティへ加工済みの値を設定します。ではSallyをfirst_name属性へ設定してみましょう。The mutator will receive the value that is being set on the attribute, allowing you to manipulate the value and set the manipulated value on the Eloquent model's internal $attributes property. So, for example, if we attempt to set the first_name attribute to Sally:
$user = App\User::find(1);
$user->first_name = 'Sally';
上記の場合、setFirstNameAttributeメソッドが呼び出され、Sallyの値が渡されます。このミューテタはそれから名前にstrtolowerを適用し、その値を$attributes内部配列へ設定します。In this example, the setFirstNameAttribute function 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 internal $attributes array.
日付ミューテタDate Mutators
デフォルトでEloquentはcreated_atとupdated_atカラムをCarbonインスタンスへ変換します。CarbonはPHPネイティブのDateTimeクラスを拡張しており、便利なメソッドを色々と提供しています。モデルの$datesプロパティをセットすることにより、データ属性を追加できます。By default, Eloquent will convert 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 add additional date attributes by setting the $dates property of your model:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 日付を変形する属性
*
* @var array
*/
protected $dates = [
'seen_at',
];
}
">Tip!! モデルの
$timestampsプロパティをfalseへセットすることにより、デフォルトのcreated_atとupdated_atタイムスタンプを無効にできます。{tip} You may disable the defaultcreated_atandupdated_attimestamps by setting the public$timestampsproperty of your model tofalse.
日付だと推定されるカラムで、値はUnixタイムスタンプ、日付文字列(Y-m-d)、日付時間文字列、DateTimeやCarbonインスタンスを値としてセットできます。日付の値は自動的に正しく変換され、データベースへ保存されます。When a column is considered a date, you may set its 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:
$user = App\User::find(1);
$user->deleted_at = now();
$user->save();
前記の通り$datesプロパティにリストした属性を取得する場合、自動的にCarbonインスタンスへキャストされますので、その属性でCarbonのメソッドがどれでも使用できます。As noted above, when retrieving attributes that are listed in your $dates property, they will automatically be cast to Carbon[https://github.com/briannesbitt/Carbon] instances, allowing you to use any of Carbon's methods on your attributes:
$user = App\User::find(1);
return $user->deleted_at->getTimestamp();
DateフォーマットDate Formats
デフォルトのタイムスタンプフォーマットは'Y-m-d H:i:s'です。タイムスタンプフォーマットをカスタマイズする必要があるなら、モデルの$dateFormatプロパティを設定してください。このプロパティは日付属性がデータベースにどのように保存されるかを決定します。By default, timestamps are formatted as 'Y-m-d H:i:s'. If you need to customize the timestamp format, set the $dateFormat property on your model. This property determines how date attributes are stored in the database:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
/**
* モデルの日付カラムの保存形式
*
* @var string
*/
protected $dateFormat = 'U';
}
属性キャストAttribute Casting
モデルの$castsプロパティは属性を一般的なデータタイプへキャストする便利な手法を提供します。$castsプロパティは配列で、キーにはキャストする属性名を指定し、値にはそのカラムに対してキャストしたいタイプを指定します。サポートしているキャストタイプはinteger、real、float、double、decimal:<桁数>、string、boolean、object、array、collection、date、datetime、timestampです。decimalへキャストする場合は、桁数をdecimal:2のように定義してください。The $casts property on your model provides a convenient method of converting attributes to common data types. 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: integer, real, float, double, decimal:<digits>, string, boolean, object, array, collection, date, datetime, and timestamp. When casting to decimal, you must define the number of digits (decimal:2).
属性キャストのデモンストレーションとして、データベースには整数の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;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* キャストする属性
*
* @var array
*/
protected $casts = [
'is_admin' => 'boolean',
];
}
これでデータベースには整数で保存されていてもis_admin属性にアクセスすれば、いつでも論理値にキャストされます。Now 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\User::find(1);
if ($user->is_admin) {
//
}
Note:
nullの属性はキャストされません。さらに、決して関係と同じ名前のキャスト（もしくは属性）を定義してはいけません。{note} Attributes that arenullwill not be cast. In addition, you should never define a cast (or an attribute) that has the same name as a relationship.
カスタムキャストCustom Casts
Laravelには多様な利便性のあるキャストタイプが用意されています。しかし、自分自身でキャストタイプを定義する必要が起きることもまれにあります。これを行うには、CastsAttributesインターフェイスを実装したクラスを定義してください。Laravel has a variety of built-in, helpful cast types; however, you may occasionally need to define your own cast types. You may accomplish this by defining a class that implements the CastsAttributes interface.
このインターフェイスを実装するクラスでは、getとsetメソッドを定義します。getメソッドはデータベースにある元の値をキャストした値へ変換することに責任を持ちます。一方のsetメソッドはキャストされている値をデータベースに保存できる元の値に変換します。例として、組み込み済みのjsonキャストタイプをカスタムキャストタイプとして再実装してみましょう。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;
class Json implements CastsAttributes
{
/**
* 指定された値をキャストする
*
* @param \Illuminate\Database\Eloquent\Model $model
* @param string $key
* @param mixed $value
* @param array $attributes
* @return array
*/
public function get($model, $key, $value, $attributes)
{
return json_decode($value, true);
}
/**
* 指定された値を保存用に準備
*
* @param \Illuminate\Database\Eloquent\Model $model
* @param string $key
* @param array $value
* @param array $attributes
* @return string
*/
public function set($model, $key, $value, $attributes)
{
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;
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\Address;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use InvalidArgumentException;
class Address implements CastsAttributes
{
/**
* 指定された値をキャスト
*
* @param \Illuminate\Database\Eloquent\Model $model
* @param string $key
* @param mixed $value
* @param array $attributes
* @return \App\Address
*/
public function get($model, $key, $value, $attributes)
{
return new Address(
$attributes['address_line_one'],
$attributes['address_line_two']
);
}
/**
* 指定された値を保存用に準備
*
* @param \Illuminate\Database\Eloquent\Model $model
* @param string $key
* @param \App\Address $value
* @param array $attributes
* @return array
*/
public function set($model, $key, $value, $attributes)
{
if (! $value instanceof Address) {
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:
$user = App\User::find(1);
$user->address->lineOne = 'Updated Address Value';
$user->save();
">Tip!! 値オブジェクトを含むEloquentモデルをJSONが配列にシリアライズする場合は、値オブジェクトに
Illuminate\Contracts\Support\ArrayableおよびJsonSerializableインターフェースを実装する必要があります。{tip} If you plan to serialize your Eloquent models containing value objects to JSON or arrays, you should implement theIlluminate\Contracts\Support\ArrayableandJsonSerializableinterfaces on the value object.
インバウンドキャストInbound Casting
モデルから属性を取得するときには何も実行せずに、モデルに保存するときだけ値を変換するカスタムキャストを書く必要があることも稀にあるでしょう。インバウンドのみのキャストの古典的な例は「ハッシュ」キャストです。インバウンドオンリーのカスタムキャストはCastsInboundAttributesインターフェイスを実装し、setメソッドを定義する必要だけがあります。Occasionally, you may need to write a custom cast 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. A classic example of an inbound only cast is a "hashing" cast. Inbound only custom casts should implement the CastsInboundAttributes interface, which only requires a set method to be defined.
<?php
namespace App\Casts;
use Illuminate\Contracts\Database\Eloquent\CastsInboundAttributes;
class Hash implements CastsInboundAttributes
{
/**
* ハッシュアルゴリズム
*
* @var string
*/
protected $algorithm;
/**
* 新キャストクラスインスタンスの生成
*
* @param string|null $algorithm
* @return void
*/
public function __construct($algorithm = null)
{
$this->algorithm = $algorithm;
}
/**
* 指定された値を保存用に準備
*
* @param \Illuminate\Database\Eloquent\Model $model
* @param string $key
* @param array $value
* @param array $attributes
* @return string
*/
public function set($model, $key, $value, $attributes)
{
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',
];
CastableCastables
モデルにカスタムキャストを指定する代わりに、Illuminate\Contracts\Database\Eloquent\Castableインターフェイスを実装するクラスを指定することも可能です。Instead of attaching the custom cast to your model, you may alternatively attach a class that implements the Illuminate\Contracts\Database\Eloquent\Castable interface:
protected $casts = [
'address' => \App\Address::class,
];
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;
use Illuminate\Contracts\Database\Eloquent\Castable;
use App\Casts\Address as AddressCast;
class Address implements Castable
{
/**
* キャスト対象をキャストするときに使用するキャスタクラス名を取得
*
* @return string
*/
public static function castUsing()
{
return AddressCast::class;
}
}
Castableクラス使用時も、$casts定義中で引数を指定可能です。引数はキャスタクラスへ直接渡されます。When using Castable classes, you may still provide arguments in the $casts definition. The arguments will be passed directly to the caster class:
protected $casts = [
'address' => \App\Address::class.':argument',
];
配列とJSONのキャストArray & JSON Casting
arrayキャストタイプは、シリアライズされたJSON形式で保存されているカラムを取り扱う場合とくに便利です。たとえば、データベースにシリアライズ済みのJSONを持つJSONかTEXTフィールドがある場合です。その属性にarrayキャストを追加すれば、Eloquentモデルにアクセスされた時点で自動的に非シリアライズ化され、PHPの配列へとキャストされます。The array cast type 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;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* キャストする属性
*
* @var array
*/
protected $casts = [
'options' => 'array',
];
}
キャストを定義後、options属性にアクセスすると自動的に非シリアライズされ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:
$user = App\User::find(1);
$options = $user->options;
$options['key'] = 'value';
$user->options = $options;
$user->save();
日付のキャストDate Casting
dateやdatetimeキャストタイプを使用する場合、日付のフォーマットを指定できます。このフォーマットは、モデルを配列やJSONへシリアライズする場合に使用します。When using the date or datetime cast type, you may 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',
];
クエリ時のキャスト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\Post;
use App\User;
$users = User::select([
'users.*',
'last_posted_at' => Post::selectRaw('MAX(created_at)')
->whereColumn('user_id', 'users.id')
])->get();
このクエリ結果上のlast_posted_at属性は元の文字列です。クエリ実行時にこの属性に対して、dateキャストを適用できると便利です。そのためには、withCastsメソッドを使用します。The last_posted_at attribute on the results of this query will be a raw string. It would be convenient if we could apply a date cast to this attribute when executing the query. To accomplish this, we may use 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();