Laravel 5.6 Eloquent：利用の開始

イントロダクションIntroduction

Eloquent ORMはLaravelに含まれている、美しくシンプルなアクティブレコードによるデーター操作の実装です。それぞれのデータベーステーブルは関連する「モデル」と結びついています。モデルによりテーブル中のデータをクエリできますし、さらに新しいレコードを追加することもできます。The Eloquent ORM included with Laravel provides a beautiful, simple ActiveRecord implementation for working with your database. Each database table has a corresponding "Model" which is used to interact with that table. Models allow you to query for data in your tables, as well as insert new records into the table.

使用開始前にconfig/database.phpを確実に設定してください。データベースの詳細はドキュメントで確認してください。Before getting started, be sure to configure a database connection in config/database.php. For more information on configuring your database, check out the documentation[/docs/{{version}}/database#configuration].

モデル定義Defining Models

利用を開始するには、まずEloquentモデルを作成しましょう。通常モデルはappディレクトリ下に置きますが、composer.jsonファイルでオートロードするように指定した場所であれば、どこでも自由に設置できます。全てのEloquentモデルは、Illuminate\Database\Eloquent\Modelを拡張する必要があります。To get started, let's create an Eloquent model. Models typically live in the app directory, but you are free to place them anywhere that can be auto-loaded according to your composer.json file. All Eloquent models extend Illuminate\Database\Eloquent\Model class.

モデルを作成する一番簡単な方法はmake:model Artisanコマンドを使用することです。The easiest way to create a model instance is using the make:model Artisan command[/docs/{{version}}/artisan]:

php artisan make:model Flight

モデル作成時にデータベースマイグレーションも生成したければ、--migrationか-mオプションを使ってください。If you would like to generate a database migration[/docs/{{version}}/migrations] when you generate the model, you may use the --migration or -m option:

php artisan make:model Flight --migration

php artisan make:model Flight -m

Eloquentモデル規約Eloquent Model Conventions

ではflightsデータベーステーブルに情報を保存し、取得するために使用するFlightモデルクラスを例として見てください。Now, let's look at an example Flight model, which we will use to retrieve and store information from our flights database table:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    //
}

テーブル名Table Names

Flightモデルにどのテーブルを使用するか、Eloquentに指定していない点に注目してください。他の名前を明示的に指定しない限り、クラス名を複数形の「スネークケース」にしたものが、テーブル名として使用されます。今回の例で、EloquentはFlightモデルをflightsテーブルに保存します。モデルのtableプロパティを定義し、カスタムテーブル名を指定することもできます。Note that we did not tell Eloquent which table to use for our Flight model. By convention, the "snake case", plural name of the class will be used as the table name unless another name is explicitly specified. So, in this case, Eloquent will assume the Flight model stores records in the flights table. You may specify a custom table by defining a table property on your model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルと関連しているテーブル
     *
     * @var string
     */
    protected $table = 'my_flights';
}

主キーPrimary Keys

Eloquentは更にテーブルの主キーがidというカラム名であると想定しています。この規約をオーバーライドする場合は、protectedのprimaryKeyプロパティを定義してください。Eloquent will also assume that each table has a primary key column named id. You may define a protected $primaryKey property to override this convention.

さらに、Eloquentは主キーを自動増分される整数値であるとも想定しています。つまり、デフォルト状態で主キーは自動的にintへキャストされます。自動増分ではない、もしくは整数値ではない主キーを使う場合、モデルにpublicの$incrementingプロパティを用意し、falseをセットしてください。主キーが整数でない場合は、モデルのprotectedの$keyTypeプロパティへstring値を設定してください。In addition, Eloquent assumes that the primary key is an incrementing integer value, which means that by default the primary key will be cast to an int automatically. If you wish to use a non-incrementing or a non-numeric primary key you must set the public $incrementing property on your model to false. If your primary key is not an integer, you should set the protected $keyType property on your model to string.

タイムスタンプTimestamps

デフォルトでEloquentはデータベース上に存在するcreated_at(作成時間)とupdated_at(更新時間)カラムを自動的に更新します。これらのカラムの自動更新をEloquentにしてほしくない場合は、モデルの$timestampsプロパティをfalseに設定してください。By default, Eloquent expects created_at and updated_at columns to exist on your tables. If you do not wish to have these columns automatically managed by Eloquent, set the $timestamps property on your model to false:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルのタイムスタンプを更新するかの指示
     *
     * @var bool
     */
    public $timestamps = false;
}

タイムスタンプのフォーマットをカスタマイズする必要があるなら、モデルの$dateFormatプロパティを設定してください。このプロパティはデータベースに保存される日付属性のフォーマットを決めるために使用されると同時に、配列やJSONへシリアライズする時にも使われます。If you need to customize the format of your timestamps, set the $dateFormat property on your model. This property determines how date attributes are stored in the database, as well as their format when the model is serialized to an array or JSON:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルの日付カラムの保存フォーマット
     *
     * @var string
     */
    protected $dateFormat = 'U';
}

タイムスタンプを保存するカラム名をカスタマイズする必要がある場合、モデルにCREATED_ATとUPDATED_AT定数を設定してください。If you need to customize the names of the columns used to store the timestamps, you may set the CREATED_AT and UPDATED_AT constants in your model:

<?php

class Flight extends Model
{
    const CREATED_AT = 'creation_date';
    const UPDATED_AT = 'last_update';
}

データベース接続Database Connection

Eloquentモデルはデフォルトとして、アプリケーションに設定されているデフォルトのデータベース接続を使用します。モデルで異なった接続を指定したい場合は、$connectionプロパティを使用します。By default, all Eloquent models will use the default database connection configured for your application. If you would like to specify a different connection for the model, use the $connection property:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * モデルで使用するコネクション名
     *
     * @var string
     */
    protected $connection = 'connection-name';
}

モデルの取得Retrieving Models

モデルと対応するデータベーステーブルを作成したら、データベースからデータを取得できるようになりました。各Eloquentモデルは、対応するデータベーステーブルへすらすらとクエリできるようにしてくれるクエリビルダだと考えてください。例を見てください。Once you have created a model and its associated database table[/docs/{{version}}/migrations#writing-migrations], you are ready to start retrieving data from your database. Think of each Eloquent model as a powerful query builder[/docs/{{version}}/queries] allowing you to fluently query the database table associated with the model. For example:

<?php

use App\Flight;

$flights = App\Flight::all();

foreach ($flights as $flight) {
    echo $flight->name;
}

制約の追加Adding Additional Constraints

Eloquentのallメソッドはモデルテーブルの全レコードを結果として返します。Eloquentモデルはクエリビルダとしても動作しますのでクエリに制約を付け加えることもでき、結果を取得するにはgetメソッドを使用します。The Eloquent all method will return all of the results in the model's table. Since each Eloquent model serves as a query builder[/docs/{{version}}/queries], you may also add constraints to queries, and then use the get method to retrieve the results:

$flights = App\Flight::where('active', 1)
               ->orderBy('name', 'desc')
               ->take(10)
               ->get();

lightbulb">Tip!! Eloquentモデルはクエリビルダですから、クエリビルダで使用できる全メソッドを確認しておくべきでしょう。Eloquentクエリでどんなメソッドも使用できます。{tip} Since Eloquent models are query builders, you should review all of the methods available on the query builder[/docs/{{version}}/queries]. You may use any of these methods in your Eloquent queries.

コレクションCollections

複数の結果を取得するallやgetのようなEloquentメソッドは、Illuminate\Database\Eloquent\Collectionインスタンスを返します。CollectionクラスはEloquent結果を操作する多くの便利なクラスを提供しています。For Eloquent methods like all and get which retrieve multiple results, an instance of Illuminate\Database\Eloquent\Collection will be returned. The Collection class provides a variety of helpful methods[/docs/{{version}}/eloquent-collections#available-methods] for working with your Eloquent results:

$flights = $flights->reject(function ($flight) {
    return $flight->cancelled;
});

もちろんこのコレクションは配列のようにループさせることもできます。Of course, you may also loop over the collection like an array:

foreach ($flights as $flight) {
    echo $flight->name;
}

結果の分割Chunking Results

数千のEloquentレコードを処理する必要がある場合はchunkコマンドを利用してください。chunkメソッドはEloquentモデルの「塊(chunk)」を取得し、引数の「クロージャ」に渡します。chunkメソッドを使えば大きな結果を操作するときのメモリを節約できます。If you need to process thousands of Eloquent records, use the chunk command. The chunk method will retrieve a "chunk" of Eloquent models, feeding them to a given Closure for processing. Using the chunk method will conserve memory when working with large result sets:

Flight::chunk(200, function ($flights) {
    foreach ($flights as $flight) {
        //
    }
});

最初の引数には「チャンク（塊）」ごとにいくつのレコードを処理するかを渡します。２番めの引数にはクロージャを渡し、そのデータベースからの結果をチャンクごとに処理するコードを記述します。クロージャへ渡されるチャンクを取得するたびに、データベースクエリは実行されます。The first argument passed to the method is the number of records you wish to receive per "chunk". The Closure passed as the second argument will be called for each chunk that is retrieved from the database. A database query will be executed to retrieve each chunk of records passed to the Closure.

カーソルの使用Using Cursors

cursorメソッドにより、ひとつだけクエリを実行するカーソルを使用し、データベース全体を繰り返し処理できます。大量のデータを処理する場合、cursorメソッドを使用すると、大幅にメモリ使用量を減らせるでしょう。The cursor method allows you to iterate through your database records using a cursor, which will only execute a single query. When processing large amounts of data, the cursor method may be used to greatly reduce your memory usage:

foreach (Flight::where('foo', 'bar')->cursor() as $flight) {
    //
}

１モデル／集計の取得Retrieving Single Models / Aggregates

もちろん指定したテーブルの全レコードを取得することに加え、findとfirstを使い１レコードだけを取得できます。モデルのコレクションの代わりに、これらのメソッドは１モデルインスタンスを返します。Of course, in addition to retrieving all of the records for a given table, you may also retrieve single records using find or first. Instead of returning a collection of models, these methods return a single model instance:

// 主キーで指定したモデル取得
$flight = App\Flight::find(1);

// クエリ条件にマッチした最初のレコード取得
$flight = App\Flight::where('active', 1)->first();

また、主キーの配列をfindメソッドに渡し、呼び出すこともできます。一致したレコードのコレクションが返されます。You may also call the find method with an array of primary keys, which will return a collection of the matching records:

$flights = App\Flight::find([1, 2, 3]);

Not Found例外Not Found Exceptions

モデルが見つからない時に、例外を投げたい場合もあります。これは特にルートやコントローラの中で便利です。findOrFailメソッドとクエリの最初の結果を取得するfirstOrFailメソッドは、該当するレコードが見つからない場合にIlluminate\Database\Eloquent\ModelNotFoundException例外を投げます。Sometimes you may wish to throw an exception if a model is not found. This is particularly useful in routes or controllers. The findOrFail and firstOrFail methods will retrieve the first result of the query; however, if no result is found, a Illuminate\Database\Eloquent\ModelNotFoundException will be thrown:

$model = App\Flight::findOrFail(1);

$model = App\Flight::where('legs', '>', 100)->firstOrFail();

この例外がキャッチされないと自動的に404HTTPレスポンスがユーザーに送り返されます。これらのメソッドを使用すればわざわざ明確に404レスポンスを返すコードを書く必要はありません。If the exception is not caught, a 404 HTTP response is automatically sent back to the user. It is not necessary to write explicit checks to return 404 responses when using these methods:

Route::get('/api/flights/{id}', function ($id) {
    return App\Flight::findOrFail($id);
});

集計の取得Retrieving Aggregates

もちろんクエリビルダが提供しているcount、sum、maxや、その他の集計関数を使用することもできます。これらのメソッドは完全なモデルインスタンスではなく、最適なスカラー値を返します。You may also use the count, sum, max, and other aggregate methods[/docs/{{version}}/queries#aggregates] provided by the query builder[/docs/{{version}}/queries]. These methods return the appropriate scalar value instead of a full model instance:

$count = App\Flight::where('active', 1)->count();

$max = App\Flight::where('active', 1)->max('price');

モデルの追加と更新Inserting & Updating Models

InsertsInserts

モデルから新しいレコードを作成するには新しいインスタンスを作成し、saveメソッドを呼び出します。To create a new record in the database, create a new model instance, set attributes on the model, then call the save method:

<?php

namespace App\Http\Controllers;

use App\Flight;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class FlightController extends Controller
{
    /**
     * 新しいflightインスタンスの生成
     *
     * @param  Request  $request
     * @return Response
     */
    public function store(Request $request)
    {
        // リクエストのバリデート処理…

        $flight = new Flight;

        $flight->name = $request->name;

        $flight->save();
    }
}

この例では、受信したHTTPリクエストのnameパラメーターをApp\Flightモデルインスタンスのname属性に代入しています。saveメソッドが呼ばれると新しいレコードがデータベースに挿入されます。saveが呼び出された時にcreated_atとupdated_atタイムスタンプは自動的に設定されますので、わざわざ設定する必要はありません。In this example, we assign the name parameter from the incoming HTTP request to the name attribute of the App\Flight model instance. When we call the save method, a record will be inserted into the database. The created_at and updated_at timestamps will automatically be set when the save method is called, so there is no need to set them manually.

UpdatesUpdates

saveメソッドはデータベースで既に存在するモデルを更新するためにも使用されます。モデルを更新するにはまず取得する必要があり、更新したい属性をセットしてそれからsaveメソッドを呼び出します。この場合もupdated_atタイムスタンプは自動的に更新されますので、値を指定する手間はかかりません。The save method may also be used to update models that already exist in the database. To update a model, you should retrieve it, set any attributes you wish to update, and then call the save method. Again, the updated_at timestamp will automatically be updated, so there is no need to manually set its value:

$flight = App\Flight::find(1);

$flight->name = 'New Flight Name';

$flight->save();

複数モデル更新Mass Updates

指定したクエリに一致する複数のモデルに対し更新することもできます。以下の例ではactiveで到着地(destination)がSan Diegoの全フライトに遅延(delayed)のマークを付けています。Updates can also be performed against any number of models that match a given query. In this example, all flights that are active and have a destination of San Diego will be marked as delayed:

App\Flight::where('active', 1)
          ->where('destination', 'San Diego')
          ->update(['delayed' => 1]);

updateメソッドは更新したいカラムと値の配列を受け取ります。The update method expects an array of column and value pairs representing the columns that should be updated.

Note: note Eloquentの複数モデル更新を行う場合、更新モデルに対するsavedとupdatedモデルイベントは発行されません。その理由は複数モデル更新を行う時、実際にモデルが取得されるわけではないからです。{note} When issuing a mass update via Eloquent, the saved and updated model events will not be fired for the updated models. This is because the models are never actually retrieved when issuing a mass update.

複数代入Mass Assignment

一行だけで新しいモデルを保存するには、createメソッドが利用できます。挿入されたモデルインスタンスが、メソッドから返されます。しかし、これを利用する前に、Eloquentモデルはデフォルトで複数代入から保護されているため、モデルへfillableかguarded属性のどちらかを設定する必要があります。You may also use the create method to save a new model in a single line. The inserted model instance will be returned to you from the method. However, before doing so, you will need to specify either a fillable or guarded attribute on the model, as all Eloquent models protect against mass-assignment by default.

複数代入の脆弱性はリクエストを通じて予期しないHTTPパラメーターが送られた時に起き、そのパラメーターはデータベースのカラムを予期しないように変更してしまうでしょう。たとえば悪意のあるユーザーがHTTPパラメーターでis_adminパラメーターを送り、それがモデルのcreateメソッドに対して渡されると、そのユーザーは自分自身を管理者(administrator)に昇格できるのです。A mass-assignment vulnerability occurs when a user passes an unexpected HTTP parameter through a request, and that parameter changes a column in your database you did not expect. For example, a malicious user might send an is_admin parameter through an HTTP request, which is then passed into your model's create method, allowing the user to escalate themselves to an administrator.

ですから最初に複数代入したいモデルの属性を指定してください。モデルの$fillableプロパティで指定できます。たとえば、Flightモデルの複数代入でname属性のみ使いたい場合です。So, to get started, you should define which model attributes you want to make mass assignable. You may do this using the $fillable property on the model. For example, let's make the name attribute of our Flight model mass assignable:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 複数代入する属性
     *
     * @var array
     */
    protected $fillable = ['name'];
}

複数代入する属性を指定したら、新しいレコードをデータベースに挿入するためにcreateが利用できます。createメソッドは保存したモデルインスタンスを返します。Once we have made the attributes mass assignable, we can use the create method to insert a new record in the database. The create method returns the saved model instance:

$flight = App\Flight::create(['name' => 'Flight 10']);

既に存在するモデルインスタンスへ属性を指定したい場合は、fillメソッドを使い、配列で指定してください。If you already have a model instance, you may use the fill method to populate it with an array of attributes:

$flight->fill(['name' => 'Flight 22']);

属性の保護Guarding Attributes

$fillableが複数代入時における属性の「ホワイトリスト」として動作する一方、$guardedの使用を選ぶことができます。$guardedプロパティは複数代入したくない属性の配列です。配列に含まれない他の属性は全部複数代入可能です。そのため$guardedは「ブラックリスト」として働きます。もちろん$fillableか$guardedのどちらか一方を使用してください。両方一度には使えません。以下の例は、priceを除いた全属性に複数代入できます。While $fillable serves as a "white list" of attributes that should be mass assignable, you may also choose to use $guarded. The $guarded property should contain an array of attributes that you do not want to be mass assignable. All other attributes not in the array will be mass assignable. So, $guarded functions like a "black list". Of course, you should use either $fillable or $guarded - not both. In the example below, all attributes except for price will be mass assignable:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 複数代入しない属性
     *
     * @var array
     */
    protected $guarded = ['price'];
}

全属性を複数代入可能にする場合は、$guardedプロパティに空の配列を定義します。If you would like to make all attributes mass assignable, you may define the $guarded property as an empty array:

/**
 * 複数代入しない属性
 *
 * @var array
 */
protected $guarded = [];

他の生成メソッドOther Creation Methods

firstOrCreate/ firstOrNewfirstOrCreate/ firstOrNew

他にも属性の複数代入可能な生成メソッドが２つあります。firstOrCreateとfirstOrNewです。firstOrCreateメソッドは指定されたカラム／値ペアでデータベースレコードを見つけようします。モデルがデータベースで見つからない場合は、最初の引数が表す属性、任意の第２引数があればそれが表す属性も同時に含む、レコードが挿入されます。There are two other methods you may use to create models by mass assigning attributes: firstOrCreate and firstOrNew. The firstOrCreate method will attempt to locate a database record using the given column / value pairs. If the model can not be found in the database, a record will be inserted with the attributes from the first parameter, along with those in the optional second parameter.

firstOrNewメソッドもfirstOrCreateのように指定された属性にマッチするデータベースのレコードを見つけようとします。しかしモデルが見つからない場合、新しいモデルインスタンスが返されます。firstOrNewが返すモデルはデータベースに保存されていないことに注目です。保存するにはsaveメソッドを呼び出す必要があります。The firstOrNew method, like firstOrCreate will attempt to locate a record in the database matching the given attributes. However, if a model is not found, a new model instance will be returned. Note that the model returned by firstOrNew has not yet been persisted to the database. You will need to call save manually to persist it:

// nameでフライトを取得するか、存在しなければ作成する
$flight = App\Flight::firstOrCreate(['name' => 'Flight 10']);

// nameでフライトを取得するか、存在しなければ指定されたnameとdelayedを含め、インスタンス化する
$flight = App\Flight::firstOrCreate(
    ['name' => 'Flight 10'], ['delayed' => 1]
);

// nameで取得するか、インスタンス化する
$flight = App\Flight::firstOrNew(['name' => 'Flight 10']);

// nameで取得するか、nameとdelayedを含めインスタンス化する
$flight = App\Flight::firstOrNew(
    ['name' => 'Flight 10'], ['delayed' => 1]
);

updateOrCreateupdateOrCreate

また、既存のモデルを更新するか、存在しない場合は新しいモデルを作成したい状況も存在します。これを一度に行うために、LaravelではupdateOrCreateメソッドを提供しています。firstOrCreateメソッドと同様に、updateOrCreateもモデルを保存するため、save()を呼び出す必要はありません。You may also come across situations where you want to update an existing model or create a new model if none exists. Laravel provides an updateOrCreate method to do this in one step. Like the firstOrCreate method, updateOrCreate persists the model, so there's no need to call save():

// OaklandからSan Diego行きの飛行機があれば、料金へ９９ドルを設定する。
// 一致するモデルがなければ、作成する。
$flight = App\Flight::updateOrCreate(
    ['departure' => 'Oakland', 'destination' => 'San Diego'],
    ['price' => 99]
);

モデル削除Deleting Models

モデルを削除するには、モデルに対しdeleteメソッドを呼び出します。To delete a model, call the delete method on a model instance:

$flight = App\Flight::find(1);

$flight->delete();

キーによる既存モデルの削除Deleting An Existing Model By Key

上記の例ではdeleteメソッドを呼び出す前にデータベースからモデルを取得しています。しかしモデルの主キーが分かっている場合なら、モデルを取得せずに削除できます。destroyメソッドを呼び出してください。In the example above, we are retrieving the model from the database before calling the delete method. However, if you know the primary key of the model, you may delete the model without retrieving it. To do so, call the destroy method:

App\Flight::destroy(1);

App\Flight::destroy([1, 2, 3]);

App\Flight::destroy(1, 2, 3);

クエリによるモデル削除Deleting Models By Query

もちろん一連のモデルに対する削除文を実行することもできます。次の例はactiveではない印を付けられたフライトを削除しています。複数モデル更新と同様に、複数削除は削除されるモデルに対するモデルイベントを発行しません。Of course, you may also run a delete statement on a set of models. In this example, we will delete all flights that are marked as inactive. Like mass updates, mass deletes will not fire any model events for the models that are deleted:

$deletedRows = App\Flight::where('active', 0)->delete();

Note: note 複数削除文をEloquentにより実行する時、削除対象モデルに対するdeletingとdeletedモデルイベントは発行されません。なぜなら、削除文の実行時に、実際にそのモデルが取得されるわけではないためです。{note} When executing a mass delete statement via Eloquent, the deleting and deleted model events will not be fired for the deleted models. This is because the models are never actually retrieved when executing the delete statement.

ソフトデリートSoft Deleting

実際にデータベースからレコードを削除する方法に加え、Eloquentはモデルの「ソフトデリート」も行えます。モデルがソフトデリートされても実際にはデータベースのレコードから削除されません。代わりにそのモデルにdeleted_at属性がセットされ、データベースへ書き戻されます。モデルのdeleted_atの値がNULLでない場合、ソフトデリートされています。モデルのソフトデリートを有効にするにはモデルにIlluminate\Database\Eloquent\SoftDeletesトレイトを使い、deleted_atカラムを$datesプロパティに追加します。In addition to actually removing records from your database, Eloquent can also "soft delete" models. When models are soft deleted, they are not actually removed from your database. Instead, a deleted_at attribute is set on the model and inserted into the database. If a model has a non-null deleted_at value, the model has been soft deleted. To enable soft deletes for a model, use the Illuminate\Database\Eloquent\SoftDeletes trait on the model and add the deleted_at column to your $dates property:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Flight extends Model
{
    use SoftDeletes;

    /**
     * 日付へキャストする属性
     *
     * @var array
     */
    protected $dates = ['deleted_at'];
}

もちろんデータベーステーブルにもdeleted_atカラムを追加する必要があります。Laravelスキーマビルダにはこのカラムを作成するメソッドが存在しています。Of course, you should add the deleted_at column to your database table. The Laravel schema builder[/docs/{{version}}/migrations] contains a helper method to create this column:

Schema::table('flights', function ($table) {
    $table->softDeletes();
});

これでモデルに対しdeleteメソッドを使用すれば、deleted_atカラムに現在の時間がセットされます。ソフトデリートされたモデルに対しクエリがあっても、削除済みのモデルはクエリ結果に含まれません。Now, when you call the delete method on the model, the deleted_at column will be set to the current date and time. And, when querying a model that uses soft deletes, the soft deleted models will automatically be excluded from all query results.

指定されたモデルインスタンスがソフトデリートされているかを確認するには、trashedメソッドを使います。To determine if a given model instance has been soft deleted, use the trashed method:

if ($flight->trashed()) {
    //
}

ソフトデリート済みモデルのクエリQuerying Soft Deleted Models

ソフトデリート済みモデルも含めるIncluding Soft Deleted Models

前述のようにソフトデリートされたモデルは自動的にクエリの結果から除外されます。しかし結果にソフトデリート済みのモデルを含めるように強制したい場合は、クエリにwithTrashedメソッドを使ってください。As noted above, soft deleted models will automatically be excluded from query results. However, you may force soft deleted models to appear in a result set using the withTrashed method on the query:

$flights = App\Flight::withTrashed()
                ->where('account_id', 1)
                ->get();

withTrashedメソッドはリレーションのクエリにも使えます。The withTrashed method may also be used on a relationship[/docs/{{version}}/eloquent-relationships] query:

$flight->history()->withTrashed()->get();

ソフトデリート済みモデルのみの取得Retrieving Only Soft Deleted Models

onlyTrashedメソッドによりソフトデリート済みのモデルのみを取得できます。The onlyTrashed method will retrieve only soft deleted models:

$flights = App\Flight::onlyTrashed()
                ->where('airline_id', 1)
                ->get();

ソフトデリートの解除Restoring Soft Deleted Models

時にはソフトデリート済みのモデルを「未削除」に戻したい場合も起きます。ソフトデリート済みモデルを有効な状態に戻すには、そのモデルインスタンスに対しrestoreメソッドを使ってください。Sometimes you may wish to "un-delete" a soft deleted model. To restore a soft deleted model into an active state, use the restore method on a model instance:

$flight->restore();

複数のモデルを手っ取り早く未削除に戻すため、クエリにrestoreメソッドを使うこともできます。他の「複数モデル」操作と同様に、この場合も復元されるモデルに対するモデルイベントは、発行されません。You may also use the restore method in a query to quickly restore multiple models. Again, like other "mass" operations, this will not fire any model events for the models that are restored:

App\Flight::withTrashed()
        ->where('airline_id', 1)
        ->restore();

withTrashedメソッドと同様、restoreメソッドはリレーションに対しても使用できます。Like the withTrashed method, the restore method may also be used on relationships[/docs/{{version}}/eloquent-relationships]:

$flight->history()->restore();

モデルの完全削除Permanently Deleting Models

データベースからモデルを本当に削除する場合もあるでしょう。データベースからソフトデリート済みモデルを永久に削除するにはforceDeleteメソッドを使います。Sometimes you may need to truly remove a model from your database. To permanently remove a soft deleted model from the database, use the forceDelete method:

// １モデルを完全に削除する
$flight->forceDelete();

// 関係するモデルを全部完全に削除する
$flight->history()->forceDelete();

クエリスコープQuery Scopes

グローバルスコープGlobal Scopes

グローバルスコープにより、指定したモデルの全クエリに対して、制約を付け加えることができます。Laravel自身のソフトデリート機能は、「削除されていない」モデルをデータベースから取得するためにグローバルスコープを使用しています。独自のグローバルスコープを書くことにより、特定のモデルのクエリに制約を確実に、簡単に、便利に指定できます。Global scopes allow you to add constraints to all queries for a given model. Laravel's own soft delete[#soft-deleting] functionality utilizes global scopes to only pull "non-deleted" models from the database. Writing your own global scopes can provide a convenient, easy way to make sure every query for a given model receives certain constraints.

グローバルスコープの記述Writing Global Scopes

グローバルスコープは簡単に書けます。Illuminate\Database\Eloquent\Scopeインターフェイスを実装したクラスを定義します。このインターフェイスは、applyメソッドだけを実装するように要求しています。applyメソッドは必要に応じ、where制約を追加します。Writing a global scope is simple. Define a class that implements the Illuminate\Database\Eloquent\Scope interface. This interface requires you to implement one method: apply. The apply method may add where constraints to the query as needed:

<?php

namespace App\Scopes;

use Illuminate\Database\Eloquent\Scope;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;

class AgeScope implements Scope
{
    /**
     * Eloquentクエリビルダへ適用するスコープ
     *
     * @param  \Illuminate\Database\Eloquent\Builder  $builder
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @return void
     */
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('age', '>', 200);
    }
}

lightbulb">Tip!! クエリのSELECT節にカラムを追加するグローバルスコープの場合は、selectの代わりにaddSelectメソッドを使用してください。これにより、クエリの存在するSELECT節を意図せずに置き換えてしまうのを防げます。{tip} If your global scope is adding columns to the select clause of the query, you should use the addSelect method instead of select. This will prevent the unintentional replacement of the query's existing select clause.

グローバルスコープの適用Applying Global Scopes

モデルにグローバルスコープを適用するには、そのモデルのbootメソッドをオーバライドし、addGlobalScopeメソッドを呼び出します。To assign a global scope to a model, you should override a given model's boot method and use the addGlobalScope method:

<?php

namespace App;

use App\Scopes\AgeScope;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * モデルの「初期起動」メソッド
     *
     * @return void
     */
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope(new AgeScope);
    }
}

スコープを追加した後から、User::all()は以下のクエリを生成するようになります。After adding the scope, a query to User::all() will produce the following SQL:

select * from `users` where `age` > 200

クロージャによるグローバルスコープAnonymous Global Scopes

Eloquentではクロージャを使ったグローバルスコープも定義できます。独立したクラスを使うだけの理由がない、簡単なスコープを使いたい場合、特に便利です。Eloquent also allows you to define global scopes using Closures, which is particularly useful for simple scopes that do not warrant a separate class:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;

class User extends Model
{
    /**
     * モデルの「初期起動」メソッド
     *
     * @return void
     */
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope('age', function (Builder $builder) {
            $builder->where('age', '>', 200);
        });
    }
}

グローバルスコープの削除Removing Global Scopes

特定のクエリからグローバルスコープを削除した場合は、withoutGlobalScopeメソッドを使います。唯一の引数として、クラス名を受けます。If you would like to remove a global scope for a given query, you may use the withoutGlobalScope method. The method accepts the class name of the global scope as its only argument:

User::withoutGlobalScope(AgeScope::class)->get();

Or, if you defined the global scope using a Closure:Or, if you defined the global scope using a Closure:

User::withoutGlobalScope('age')->get();

複数、もしくは全部のグローバルスコープを削除したい場合も、withoutGlobalScopesメソッドが使えます。If you would like to remove several or even all of the global scopes, you may use the withoutGlobalScopes method:

// 全グローバルスコープの削除
User::withoutGlobalScopes()->get();

// いくつかのグローバルスコープの削除
User::withoutGlobalScopes([
    FirstScope::class, SecondScope::class
])->get();

ローカルスコープLocal Scopes

ローカルスコープによりアプリケーション全体で簡単に再利用可能な、一連の共通制約を定義できます。例えば、人気のある(popular)ユーザーを全員取得する必要が、しばしばあるとしましょう。スコープを定義するには、scopeを先頭につけた、Eloquentモデルのメソッドを定義します。Local scopes allow you to define common sets of constraints that you may easily re-use throughout your application. For example, you may need to frequently retrieve all users that are considered "popular". To define a scope, prefix an Eloquent model method with scope.

スコープはいつもクエリビルダインスタンスを返します。Scopes should always return a query builder instance:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 人気のあるユーザーだけに限定するクエリスコープ
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopePopular($query)
    {
        return $query->where('votes', '>', 100);
    }

    /**
     * アクティブなユーザーだけに限定するクエリスコープ
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeActive($query)
    {
        return $query->where('active', 1);
    }
}

ローカルスコープの利用Utilizing A Local Scope

スコープが定義できたらモデルのクエリ時にスコープメソッドを呼び出せます。しかし、メソッドを呼び出すときはscopeプレフィックスをつけないでください。様々なスコープをチェーンでつなぎ呼び出すこともできます。例を見てください。Once the scope has been defined, you may call the scope methods when querying the model. However, you should not include the scope prefix when calling the method. You can even chain calls to various scopes, for example:

$users = App\User::popular()->active()->orderBy('created_at')->get();

動的スコープDynamic Scopes

引数を受け取るスコープを定義したい場合もあるでしょう。スコープにパラメーターを付けるだけです。スコープパラメーターは$query引数の後に定義しする必要があります。Sometimes you may wish to define a scope that accepts parameters. To get started, just add your additional parameters to your scope. Scope parameters should be defined after the $query parameter:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 指定したタイプのユーザーだけを含むクエリのスコープ
     *
     * @param \Illuminate\Database\Eloquent\Builder $query
     * @param mixed $type
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopeOfType($query, $type)
    {
        return $query->where('type', $type);
    }
}

これでスコープを呼び出すときにパラメーターを渡せます。Now, you may pass the parameters when calling the scope:

$users = App\User::ofType('admin')->get();

モデルの比較Comparing Models

時に２つのモデルが「同じ」であるかを判定する必要が起きるでしょう。isメソッドは２つのモデルが、同じ主キー、テーブル、データベース接続を持っているかを確認します。Sometimes you may need to determine if two models are the "same". The is method may be used to quickly verify two models have same primary key, table, and database connection:

if ($post->is($anotherPost)) {
    //
}

イベントEvents

Eloquentモデルは多くのイベントを発行します。creating、created、updating、updated、saving、saved、deleting、deleted、restoring、restored、retrievedのメソッドを利用し、モデルのライフサイクルの様々な時点をフックすることができます。イベントにより特定のモデルクラスが保存されたりアップデートされたりするたび、簡単にコードを実行できるようになります。Eloquent models fire several events, allowing you to hook into the following points in a model's lifecycle: retrieved, creating, created, updating, updated, saving, saved, deleting, deleted, restoring, restored. Events allow you to easily execute code each time a specific model class is saved or updated in the database.

retrievedは、データベースから既存のモデルを取得した時に発行されます。新しいアイテムが最初に保存される場合にcreatingとcreatedイベントが発行されます。既存のアイテムにsaveメソッドが呼び出されるとupdatingとupdatedイベントが発行されます。どちらの場合にもsavingとsavedイベントは発行されます。The retrieved event will fire when an existing model is retrieved from the database. When a new model is saved for the first time, the creating and created events will fire. If a model already existed in the database and the save method is called, the updating / updated events will fire. However, in both cases, the saving / saved events will fire.

Note: note Eloquentにより複数更新を実行する場合、更新したモデルに対しsavedとupdatedイベントは発行されません。この理由は複数更新実行時に、モデルが実際には取得されないからです。{note} When issuing a mass update via Eloquent, the saved and updated model events will not be fired for the updated models. This is because the models are never actually retrieved when issuing a mass update.

使用するには、Eloquentモデルに$dispatchesEventsプロパティを定義します。これにより、Eloquentモデルのライフサイクルの様々な時点を皆さん自身のイベントクラスへマップします。To get started, define a $dispatchesEvents property on your Eloquent model that maps various points of the Eloquent model's lifecycle to your own event classes[/docs/{{version}}/events]:

<?php

namespace App;

use App\Events\UserSaved;
use App\Events\UserDeleted;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * モデルのイベントマップ
     *
     * @var array
     */
    protected $dispatchesEvents = [
        'saved' => UserSaved::class,
        'deleted' => UserDeleted::class,
    ];
}

オブザーバObservers

オブザーバの定義Defining Observers

特定のモデルに対し、多くのイベントをリスニングしている場合、全リスナのグループに対するオブザーバを一つのクラスの中で使用できます。オブザーバクラスは、リッスンしたいEloquentイベントに対応する名前のメソッドを持ちます。これらのメソッドは、唯一の引数としてモデルを受け取ります。make:observer　Artisanコマンドで、新しいオブザーバクラスを簡単に生成できます。If you are listening for many events on a given model, you may use observers to group all of your listeners into a single class. Observers classes have method names which reflect the Eloquent events you wish to listen for. Each of these methods receives the model as their only argument. The make:observer Artisan command is the easiest way to create a new observer class:

php artisan make:observer UserObserver --model=User

このコマンドは、App/Observersディレクトリへ新しいオブザーバを設置します。このディレクトリが存在しなければ、Artisanが作成します。真新しいオブザーバは、次の通りです。This command will place the new observer in your App/Observers directory. If this directory does not exist, Artisan will create it for you. Your fresh observer will look like the following:

<?php

namespace App\Observers;

use App\User;

class UserObserver
{
    /**
     * ユーザーの"created"イベントを処理
     *
     * @param  \App\User  $user
     * @return void
     */
    public function created(User $user)
    {
        //
    }

    /**
     * ユーザーの"updated"イベントを処理
     *
     * @param  \App\User  $user
     * @return void
     */
    public function updated(User $user)
    {
        //
    }

    /**
     * ユーザーの"deleted"イベントを処理
     *
     * @param  \App\User  $user
     * @return void
     */
    public function deleted(User $user)
    {
        //
    }
}

オブザーバを登録するには、監視したいモデルに対し、observeメソッドを使用します。サービスプロバイダの一つの、bootメソッドで登録します。以下の例では、AppServiceProviderでオブザーバを登録しています。To register an observer, use the observe method on the model you wish to observe. You may register observers in the boot method of one of your service providers. In this example, we'll register the observer in the AppServiceProvider:

<?php

namespace App\Providers;

use App\User;
use App\Observers\UserObserver;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * アプリケーションサービスの初期起動処理
     *
     * @return void
     */
    public function boot()
    {
        User::observe(UserObserver::class);
    }

    /**
     * サービスプロバイダの登録
     *
     * @return void
     */
    public function register()
    {
        //
    }
}