Laravel 5.1 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.

使いはじめる前に確実にcofig/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 User

モデル作成時にデータベースマイグレーションも生成したければ、--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 User --migration

php artisan make:model User -m

Eloquentモデル規約Eloquent Model Conventions

ではflightsデータベーステーブルに情報を保存し、取得するために使用するFlightモデルクラスを例として見てください。Now, let's look at an example Flight model class, 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. 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というカラム名であると想定しています。この規約をオーバーライドする場合はprimaryKeyプロパティを定義してください。Eloquent will also assume that each table has a primary key column named id. You may define a $primaryKey property to override this convention.

タイムスタンプ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';
}

データベース接続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 Multiple Models

For example: モデルと対応するデータベーステーブルを作成したら、データベースからデータを取得できるようになりました。各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

namespace App\Http\Controllers;

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

class FlightController extends Controller
{
    /**
     * 利用可能な全フライトの一覧を表示
     *
     * @return Response
     */
    public function index()
    {
        $flights = Flight::all();

        return view('flight.index', ['flights' => $flights]);
    }
}

カラム値に対するアクセスAccessing Column Values

Eloquentモデルインスタンスを入手したら、モデルのカラム値には対応するプロパティとしてサクセスできます。たとえばクエリーの結果の各Flightインスタンスをループで取得し、nameカラムの値をechoしてみましょう。If you have an Eloquent model instance, you may access the column values of the model by accessing the corresponding property. For example, let's loop through each Flight instance returned by our query and echo the value of the name column:

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();

注目： Eloquentモデルはクエリービルダーですから、クエリービルダーで使用できる全メソッドを確認しておくべきでしょう。Eloquentクエリーでどんなメソッドも使用できます。Note: 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. Of course, you may simply loop over this 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.

１モデル／集計の取得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 and 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();

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, so 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やその他の集計関数を使用することもできます。これらのメソッドは完全なモデルインスタンスの代わりに最適なスカラー値を返します。Of course, you may also use count, sum, max, and other aggregate functions[/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

基本の追加Basic Inserts

モデルから新しいレコードを作成するには新しいインスタンスを作成し、saveメソッドを呼び出します。To create a new record in the database, simply 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 simply 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.

基本の更新Basic Updates

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 = '新しいフライト名';

$flight->save();

指定したクエリーに一致する複数のモデルに対し更新することもできます。以下の例では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]);

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

複数代入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.

複数代入の脆弱性はリクエストを通じて予期しない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 mapped onto 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']);

$fillableが複数代入時における属性の「ホワイトリスト」として動作する一方、$guardedの使用を選ぶことができます。$guardedプロパティーは複数代入したくない属性の配列です。配列に含まれない他の属性は全部複数台入可能です。そのため$guardedは「ブラックリスト」として働きます。もちろん$fillableか$guardedのどちらか一方を使用してください。両方一度には使えません。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:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

この例では**price以外**の全属性で複数代入ができます。In the example above, all attributes except for price will be mass assignable.

他の生成メソッドOther Creation Methods

他にも属性の複数代入可能な生成メソッドが２つあります。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 given attributes.

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:

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

// 属性のフライトか、存在しなければ新しいインスタンスを取得する…
$flight = App\Flight::firstOrNew(['name' => 'Flight 10']);

モデル削除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 query on a set of models. In this example, we will delete all flights that are marked as inactive:

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

ソフトデリート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();

WHERE節での注意Where Clause Caveats

ソフトデリート対応モデルに対し、orWhere節をクエリーに追加する時には、常に上級のWHERE節指定をWHERE節の論理グループに対して使用してください。例を見てください。When adding orWhere clauses to your queries on soft deleted models, always use advance where clauses[http://laravel.com/docs/5.1/queries#advanced-where-clauses] to logically group the WHERE clauses. For example:

User::where(function($query) {
        $query->where('name', '=', 'John')
              ->orWhere('votes', '>', 100);
        })
        ->get();

これにより、以下のSQLが生成されます。This will produce the following SQL:

select * from `users` where `users`.`deleted_at` is null and (`name` = 'John' or `votes` > 100)

orWhere節をグループに対して使用しないと、以下のようにソフトデリートしたレコードを含むようなSQLを生成します。If the orWhere clause is not grouped, it will produce the following SQL which will contain soft deleted records:

select * from `users` where `users`.`deleted_at` is null and `name` = 'John' or `votes` > 100

ソフトデリート済みモデルのみの取得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:

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

スコープはアプリケーションのどこでも簡単に共通の制約定義を再利用できるようにします。たとえば「人気がある(pupular)」と思われるユーザーを全員を頻繁に必要だとしましょう。スコープを定義するにはEloqunetモデルのメソッド名にscopeプレフィックスを付けるだけです。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, simply 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
{
    /**
     * 人気のあるユーザーだけをクエリーするスコープ
     *
     * @return \Illuminate\Database\Eloquent\Builder
     */
    public function scopePopular($query)
    {
        return $query->where('votes', '>', 100);
    }

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

クエリースコープの使用Utilizing A Query Scope

スコープが定義できたらモデルのクエリー時にスコープメソッドを呼び出せます。しかしメソッドを呼び出すときにscopeプレフィックスを付ける必要はありません。様々なスコープをチェーンでつなぎ呼び出すこともできます。例を見てください。Once the scope has been defined, you may call the scope methods when querying the model. However, you do not need to 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 argument:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 指定したタイプのユーザーだけを含むクエリーのスコープ
     *
     * @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();

イベントEvents

Eloquentモデルは多くのイベントを発行します。creating、created、updating、updated、saving、saved、deleting、deleted、restoring、restoredのメソッドを利用し、モデルのライフサイクルの様々な時点をフックすることができます。イベントにより特定のモデルクラスが保存されたりアップデートされたりするたび、簡単にコードを実行できるようになります。Eloquent models fire several events, allowing you to hook into various points in the model's lifecycle using the following methods: 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.

基本的な使用法Basic Usage

いつでも新しいアイテムが最初に保存される場合にcreatingとcreatedイベントが発行されます。新しくないアイテムにsaveメソッドが呼び出されるとupdatingとupdatedイベントが発行されます。どちらの場合にもsavingとsavedイベントは発行されます。Whenever 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.

例としてサービスプロバイダーでEloquentイベントリスナーを定義してみましょう。イベントリスナーの中で指定されたモデルに対しisValidメソッドを呼び出し、モデルが有効でなければfalseが返されます。Eloquentイベントリスナーがfalseを返すとsave／update操作はキャンセルされます。For example, let's define an Eloquent event listener in a service provider[/docs/{{version}}/providers]. Within our event listener, we will call the isValid method on the given model, and return false if the model is not valid. Returning false from an Eloquent event listener will cancel the save / update operation:

<?php

namespace App\Providers;

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

class AppServiceProvider extends ServiceProvider
{
    /**
     * 全アプリケーションサービスの初期処理
     *
     * @return void
     */
    public function boot()
    {
        User::creating(function ($user) {
            if ( ! $user->isValid()) {
                return false;
            }
        });
    }

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