イントロダクション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.
さらに、Eloquentは主キーを自動増分される整数値であるとも想定しています。つまり、デフォルト状態で主キーは自動的にintへキャストされます。自動増分ではない、もしくは整数値ではない主キーを使う場合、モデルにpublicの$incrementingプロパティーを用意し、falseをセットしてください。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.
タイムスタンプ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
モデルと対応するデータベーステーブルを作成したら、データベースからデータを取得できるようになりました。各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();
また、主キーの配列を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, 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 = 'New 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();
ソフトデリート済みモデルのみの取得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
グローバルスコープGlobal Scopes
グローバルスコープにより、指定したモデルの全クエリに対して、制約を付け加えることができます。Laravel自身のソフトデリート機能は、「削除されていない」モデルをデータベースから取得するためにグローバルスコープを使用しています。独自のグローバルスコープを書くことにより、特定のモデルのクエリに制約を確実に、簡単に、便利に指定できます。Global scopes allow you to add constraints to all queries for a given model. Laravel's own soft deleting[#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)
{
return $builder->where('age', '>', 200);
}
}
デフォルトのLaravelアプリケーションには、スコープのためのフォルダは用意されていません。Laravelアプリケーションのappディレクトリ下に、自由にScopesフォルダーを作成してください。There is not a predefined folder for scopes in a default Laravel application, so feel free to make your own Scopes folder within your Laravel application's app directory.
グローバルスコープの適用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);
});
}
}
addGlobalScopeの最初の引数は、スコープを削除する時に使用する識別子です。The first argument of the addGlobalScope() serves as an identifier to remove the scope:
User::withoutGlobalScope('age')->get();
グローバルスコープの削除Removing Global Scopes
特定のクエリからグローバルスコープを削除した場合は、withoutGlobalScopeメソッドを使います。If you would like to remove a global scope for a given query, you may use the withoutGlobalScope method:
User::withoutGlobalScope(AgeScope::class)->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, 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()
{
//
}
}