イントロダクションIntroduction
Laravelは、データベース操作を楽しくする、オブジェクトリレーショナルマッパー(ORM)であるEloquentを用意しています。Eloquentを使用する場合、各データベーステーブルに対応する「モデル」があり、そのテーブル操作に使用します。Eloquentモデルは、データベーステーブルからレコードを取得するだけでなく、テーブルへのレコード挿入、更新、削除も可能です。Laravel includes Eloquent, an object-relational mapper (ORM) that makes it enjoyable to interact with your database. When using Eloquent, each database table has a corresponding "Model" that is used to interact with that table. In addition to retrieving records from the database table, Eloquent models allow you to insert, update, and delete records from the table as well.
Note: 使用開始前に、必ずアプリケーションの
config/database.php
設定ファイルで、データベース接続を設定してください。データベース設定の詳細は、データベース設定のドキュメントで確認してください。[!NOTE]
Before getting started, be sure to configure a database connection in your application'sconfig/database.php
configuration file. For more information on configuring your database, check out the database configuration documentation[/docs/{{version}}/database#configuration].
Laravel BootcampLaravel Bootcamp
Laravelが初めての方は、Laravel Bootcampに気軽に飛び込んでみてください。Laravel Bootcampは、Eloquentを使って初めてのLaravelアプリケーションを構築する方法を説明します。LaravelとEloquentが提供するすべてを知るには最適な方法です。If you're new to Laravel, feel free to jump into the Laravel Bootcamp[https://bootcamp.laravel.com]. The Laravel Bootcamp will walk you through building your first Laravel application using Eloquent. It's a great way to get a tour of everything that Laravel and Eloquent have to offer.
モデルクラスの生成Generating Model Classes
使用を開始するには、Eloquentモデルを作成しましょう。モデルは通常app\Models
ディレクトリにあり、Illuminate\Database\Eloquent\Model
クラスを拡張します。make:model
Artisanコマンドを使用して、新しいモデルを生成します。To get started, let's create an Eloquent model. Models typically live in the app\Models
directory and extend the Illuminate\Database\Eloquent\Model
class. You may use the make:model
Artisan command[/docs/{{version}}/artisan] to generate a new model:
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
モデルを生成するとき、ファクトリ、シーダ、コントローラ、ポリシー、フォームリクエストなど、他のさまざまなタイプのクラスを同時に生成できます。さらにこれらのオプションを組み合わせて、一度に複数のクラスを作成できます。You may generate various other types of classes when generating a model, such as factories, seeders, policies, controllers, and form requests. In addition, these options may be combined to create multiple classes at once:
# モデルとFlightFactoryクラスを生成
php artisan make:model Flight --factory
php artisan make:model Flight -f
# モデルとFlightSeederクラスを生成
php artisan make:model Flight --seed
php artisan make:model Flight -s
# モデルとFlightControllerクラスを生成
php artisan make:model Flight --controller
php artisan make:model Flight -c
# モデルとFlightControllerリソースクラス、フォームリクエストクラスを生成
php artisan make:model Flight --controller --resource --requests
php artisan make:model Flight -crR
# モデルとFlightPolicyクラスを生成
php artisan make:model Flight --policy
# モデルとマイグレーション、ファクトリ、シーダ、およびコントローラを生成
php artisan make:model Flight -mfsc
# モデルとマイグレーション、ファクトリ、シーダ、ポリシー、コントローラ、フォームリクエストを生成する短縮形
php artisan make:model Flight --all
php artisan make:model Flight -a
# ピボットモデルを生成
php artisan make:model Member --pivot
php artisan make:model Member -p
モデルの調査Inspecting Models
モデルのコードに目を通すだけでは、そのモデルで利用可能な全ての属性とリレーションを判断するのが難しい場合があります。そのような場合は、model:show
Artisanコマンドを使用してください。モデルの全ての属性とリレーションを簡単に確認できます。Sometimes it can be difficult to determine all of a model's available attributes and relationships just by skimming its code. Instead, try the model:show
Artisan command, which provides a convenient overview of all the model's attributes and relations:
php artisan model:show Flight
Eloquentモデルの規約Eloquent Model Conventions
make:model
コマンドで生成されたモデルは、app/Models
ディレクトリに配置します。基本的なモデルクラスを調べて、Eloquentの主要な規約をいくつか説明しましょう。Models generated by the make:model
command will be placed in the app/Models
directory. Let's examine a basic model class and discuss some of Eloquent's key conventions:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
// ...
}
テーブル名Table Names
上記の例をちょっと見て、どのデータベーステーブルがFlight
モデルに対応するかをEloquentに知らせていないことにお気づきかもしれません。別の名前を明示的に指定しない限り、クラスの複数形の「スネークケース」をテーブル名として使用します。したがって、この場合、EloquentはFlight
モデルがflights
テーブルにレコードを格納し、AirTrafficController
モデルはair_traffic_controllers
テーブルにレコードを格納すると想定できます。After glancing at the example above, you may have noticed that we did not tell Eloquent which database table corresponds to 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, while an AirTrafficController
model would store records in an air_traffic_controllers
table.
モデルの対応するデータベーステーブルがこの規約に適合しない場合は、モデルにtable
プロパティを定義してモデルのテーブル名を自分で指定できます。If your model's corresponding database table does not fit this convention, you may manually specify the model's table name by defining a table
property on the model:
<?php
namespace App\Models;
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 model's corresponding database table has a primary key column named id
. If necessary, you may define a protected $primaryKey
property on your model to specify a different column that serves as your model's primary key:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
/**
* テーブルに関連付ける主キー
*
* @var string
*/
protected $primaryKey = 'flight_id';
}
さらに、Eloquentは、主キーが増分整数値であることも想定しています。これは、Eloquentが主キーを自動的に整数にキャストすることを意味します。非インクリメントまたは非数値の主キーを使用する場合は、モデルにpublicの$incrementing
プロパティを定義し、false
をセットする必要があります。In addition, Eloquent assumes that the primary key is an incrementing integer value, which means that Eloquent will automatically cast the primary key to an integer. If you wish to use a non-incrementing or a non-numeric primary key you must define a public $incrementing
property on your model that is set to false
:
<?php
class Flight extends Model
{
/**
* モデルのIDを自動増分するか
*
* @var bool
*/
public $incrementing = false;
}
モデルの主キーが整数でない場合は、モデルにprotectedな$keyType
プロパティを定義する必要があります。このプロパティの値はstring
にする必要があります。If your model's primary key is not an integer, you should define a protected $keyType
property on your model. This property should have a value of string
:
<?php
class Flight extends Model
{
/**
* 主キーIDのデータ型
*
* @var string
*/
protected $keyType = 'string';
}
「コンポジット」主キー"Composite" Primary Keys
Eloquentは、それぞれのモデルがその主キーとして役立つことができる、少なくとも1つの一意に識別される「ID」を持つ必要があります。Eloquentモデルは「コンポジット」主キーをサポートしていません。しかし、テーブルの一意に識別される主キーに加えて、データベーステーブルに追加のマルチカラム、ユニークなインデックスを追加することができます。Eloquent requires each model to have at least one uniquely identifying "ID" that can serve as its primary key. "Composite" primary keys are not supported by Eloquent models. However, you are free to add additional multi-column, unique indexes to your database tables in addition to the table's uniquely identifying primary key.
UUIDとULIDキーUUID and ULID Keys
Eloquentモデルの主キーへ、自動増分整数を使用する代わりに、UUIDが使用できます。UUIDは36文字の英数字で構成される一意な識別子です。Instead of using auto-incrementing integers as your Eloquent model's primary keys, you may choose to use UUIDs instead. UUIDs are universally unique alpha-numeric identifiers that are 36 characters long.
モデルで自動インクリメントの整数キーの代わりにUUIDキーを使用したい場合は、そのモデルでIlluminate\Database\Eloquent\Concerns\HasUuids
トレイトを使用します。もちろん、モデルへUUIDの主キーカラムを確実に持たせてください。If you would like a model to use a UUID key instead of an auto-incrementing integer key, you may use the Illuminate\Database\Eloquent\Concerns\HasUuids
trait on the model. Of course, you should ensure that the model has a UUID equivalent primary key column[/docs/{{version}}/migrations#column-method-uuid]:
use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Model;
class Article extends Model
{
use HasUuids;
// ...
}
$article = Article::create(['title' => 'Traveling to Europe']);
$article->id; // "8f8e8478-9035-4d23-b9a7-62f4d2612ce5"
HasUuids
トレイトはデフォルトで、モデルに対し順序付き(ordered)UUIDを生成します。これらのUUIDは辞書式にソートすることができるため、インデックス付きデータベースの保存が効率的です。By default, The HasUuids
trait will generate "ordered" UUIDs[/docs/{{version}}/strings#method-str-ordered-uuid] for your models. These UUIDs are more efficient for indexed database storage because they can be sorted lexicographically.
モデルへnewUniqueId
メソッドを定義すれば、指定モデルのUUID生成処理をオーバーライドできます。さらに、モデルにuniqueIds
メソッドを定義すれば、UUIDをどのカラムで受け取るのかを指定できます。You can override the UUID generation process for a given model by defining a newUniqueId
method on the model. In addition, you may specify which columns should receive UUIDs by defining a uniqueIds
method on the model:
use Ramsey\Uuid\Uuid;
/**
* モデルの新しいUUIDの生成
*/
public function newUniqueId(): string
{
return (string) Uuid::uuid4();
}
/**
* 一意の識別子を受け取るカラムの取得
*
* @return array<int, string>
*/
public function uniqueIds(): array
{
return ['id', 'discount_code'];
}
ご希望であれば、UUIDの代わりに"ULID"を使用することもできます。ULIDはUUIDに似ていますが、長さは26文字です。順序付きUUIDのように、ULIDは効率的なデータベースインデックス作成のため、辞書的にソート可能です。ULIDを使用するには、モデルで Illuminate\Database\Eloquent\Concerns\HasUlids
トレイトを使用してください。また、モデルにULID相当の主キーカラム確実に用意する必要があります。If you wish, you may choose to utilize "ULIDs" instead of UUIDs. ULIDs are similar to UUIDs; however, they are only 26 characters in length. Like ordered UUIDs, ULIDs are lexicographically sortable for efficient database indexing. To utilize ULIDs, you should use the Illuminate\Database\Eloquent\Concerns\HasUlids
trait on your model. You should also ensure that the model has a ULID equivalent primary key column[/docs/{{version}}/migrations#column-method-ulid]:
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Model;
class Article extends Model
{
use HasUlids;
// ...
}
$article = Article::create(['title' => 'Traveling to Asia']);
$article->id; // "01gd4d3tgrrfqeda94gdbtdk5c"
主キータイムスタンプTimestamps
デフォルトでEloquentは、モデルと対応するデータベーステーブルに、created_at
カラムとupdated_at
カラムが存在していると想定します。Eloquentはモデルが作成または更新されるときに、これらの列の値を自動的にセットします。これらのカラムがEloquentによって自動的に管理されないようにする場合は、モデルに$timestamps
プロパティを定義し、false
値をセットします。By default, Eloquent expects created_at
and updated_at
columns to exist on your model's corresponding database table. Eloquent will automatically set these column's values when models are created or updated. If you do not want these columns to be automatically managed by Eloquent, you should define a $timestamps
property on your model with a value of false
:
<?php
namespace App\Models;
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 model's 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\Models;
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 define CREATED_AT
and UPDATED_AT
constants on your model:
<?php
class Flight extends Model
{
const CREATED_AT = 'creation_date';
const UPDATED_AT = 'updated_date';
}
モデルのupdated_at
タイムスタンプを変更せずに、モデル操作を行いたい場合は、withoutTimestamps
メソッドへ指定するクロージャ内で、そのモデルを操作できます。If you would like to perform model operations without the model having its updated_at
timestamp modified, you may operate on the model within a closure given to the withoutTimestamps
method:
Model::withoutTimestamps(fn () => $post->increment('reads'));
データベース接続Database Connections
デフォルトですべてのEloquentモデルは、アプリケーション用に設定したデフォルトのデータベース接続を使用します。特定のモデルと対話するときに別の接続を使用する必要がある場合は、モデルに$connection
プロパティを定義する必要があります。By default, all Eloquent models will use the default database connection that is configured for your application. If you would like to specify a different connection that should be used when interacting with a particular model, you should define a $connection
property on the model:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
/**
* このモデルが使用するデータベース接続
*
* @var string
*/
protected $connection = 'mysql';
}
デフォルト属性値Default Attribute Values
デフォルトでは、新しくインスタンス化するモデルインスタンスに属性値は含まれません。モデルの属性の一部にデフォルト値を定義したい場合は、モデルに$attributes
プロパティを定義できます。$attributes
配列に格納する属性値は、データベースから読み込んだままのような、素の「保存可能」形式であるべきです。By default, a newly instantiated model instance will not contain any attribute values. If you would like to define the default values for some of your model's attributes, you may define an $attributes
property on your model. Attribute values placed in the $attributes
array should be in their raw, "storable" format as if they were just read from the database:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
/**
* モデルの属性のデフォルト値
*
* @var array
*/
protected $attributes = [
'options' => '[]',
'delayed' => false,
];
}
Eloquent厳格さの設定Configuring Eloquent Strictness
Laravelは、さまざまな状況におけるEloquent動作や、「厳密さ」を設定するためメソッドを用意しています。Laravel offers several methods that allow you to configure Eloquent's behavior and "strictness" in a variety of situations.
まず、preventLazyLoading
メソッドは、オプションで論理値の引数を取り、遅延ロードを防ぐかを指定します。たとえば、非本番環境のみ遅延ロードを無効にし、本番環境にリレーションを遅延ロードするコードが誤って紛れ込んだ場合でも、正常に機能し続けるようにしたい状況はあると思います。通常、このメソッドはアプリケーションのAppServiceProvider
のboot
メソッドで呼び出す必要があります。First, the preventLazyLoading
method accepts an optional boolean argument that indicates if lazy loading should be prevented. For example, you may wish to only disable lazy loading in non-production environments so that your production environment will continue to function normally even if a lazy loaded relationship is accidentally present in production code. Typically, this method should be invoked in the boot
method of your application's AppServiceProvider
:
use Illuminate\Database\Eloquent\Model;
/**
* 全アプリケーションサービスの初期起動処理
*/
public function boot(): void
{
Model::preventLazyLoading(! $this->app->isProduction());
}
また、preventSilentlyDiscardingAttributes
メソッドを呼び出せば、複数代入非許可な属性へ複数代入しようとしたときに例外を投げるようにLaravelに指示することもできます。これは、ローカル開発時に、モデルのfillable
配列へ追加されていない属性をセットしようとしたときに、予期せぬエラーが発生するのを防ぐのに役立ちます。Also, you may instruct Laravel to throw an exception when attempting to fill an unfillable attribute by invoking the preventSilentlyDiscardingAttributes
method. This can help prevent unexpected errors during local development when attempting to set an attribute that has not been added to the model's fillable
array:
Model::preventSilentlyDiscardingAttributes(! $this->app->isProduction());
モデルの取得Retrieving Models
モデルとそれと関連するデータベーステーブルを作成したら、データベースからデータを取得する準備が整いました。各Eloquentモデルは、モデルに関連付けたデータベーステーブルを流暢にクエリできる強力なクエリビルダと考えることができます。モデルのall
メソッドは、モデルに関連付けたデータベーステーブルからすべてのレコードを取得します。Once you have created a model and its associated database table[/docs/{{version}}/migrations#generating-migrations], you are ready to start retrieving data from your database. You can 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. The model's all
method will retrieve all of the records from the model's associated database table:
use App\Models\Flight;
foreach (Flight::all() as $flight) {
echo $flight->name;
}
クエリの作成Building Queries
Eloquentのall
メソッドは、モデルのテーブルにあるすべての結果を返します。しかし、各Eloquentモデルはクエリビルダとして機能するため、クエリに制約を追加してからget
メソッドを呼び出し、結果を取得することもできます。The Eloquent all
method will return all of the results in the model's table. However, since each Eloquent model serves as a query builder[/docs/{{version}}/queries], you may add additional constraints to queries and then invoke the get
method to retrieve the results:
$flights = Flight::where('active', 1)
->orderBy('name')
->take(10)
->get();
クエリビルダが提供するすべてのメソッドを確認する必要があります。Eloquentでクエリを作成するときは、それらすべてのメソッドを使用できます。[!NOTE]
Note: Eloquentモデルはクエリビルダであるため、Laravelの
Since Eloquent models are query builders, you should review all of the methods provided by Laravel's query builder[/docs/{{version}}/queries]. You may use any of these methods when writing your Eloquent queries.
モデルのリフレッシュRefreshing Models
データベースから取得したEloquentモデルのインスタンスがすでにある場合は、fresh
メソッドとrefresh
メソッドを使用してモデルを「更新」できます。fresh
メソッドは、データベースからモデルを再取得します。既存のモデルインスタンスは影響を受けません。If you already have an instance of an Eloquent model that was retrieved from the database, you can "refresh" the model using the fresh
and refresh
methods. The fresh
method will re-retrieve the model from the database. The existing model instance will not be affected:
$flight = Flight::where('number', 'FR 900')->first();
$freshFlight = $flight->fresh();
refresh
メソッドは、データベースからの新しいデータを使用して既存のモデルを再ハイドレートします。さらに、ロードしたすべてのリレーションも更新されます。The refresh
method will re-hydrate the existing model using fresh data from the database. In addition, all of its loaded relationships will be refreshed as well:
$flight = Flight::where('number', 'FR 900')->first();
$flight->number = 'FR 456';
$flight->refresh();
$flight->number; // "FR 900"
コレクションCollections
これまで見てきたように、all
やget
のようなEloquentメソッドは、データベースから複数のレコードを取得します。ただし、これらのメソッドはプレーンなPHP配列を返しません。代わりに、Illuminate\Database\Eloquent\Collection
のインスタンスが返されます。As we have seen, Eloquent methods like all
and get
retrieve multiple records from the database. However, these methods don't return a plain PHP array. Instead, an instance of Illuminate\Database\Eloquent\Collection
is returned.
Eloquent Collection
クラスはLaravelの基本Illuminate\Support\Collection
クラスを拡張し、データコレクションを操作するためにさまざまな便利なメソッドを提供しています。たとえば、reject
メソッドを使用して、呼び出されたクロージャの結果に基づいてコレクションからモデルを削除できます。The Eloquent Collection
class extends Laravel's base Illuminate\Support\Collection
class, which provides a variety of helpful methods[/docs/{{version}}/collections#available-methods] for interacting with data collections. For example, the reject
method may be used to remove models from a collection based on the results of an invoked closure:
$flights = Flight::where('destination', 'Paris')->get();
$flights = $flights->reject(function (Flight $flight) {
return $flight->cancelled;
});
Laravelの基本コレクションクラスによって提供されるメソッドに加えて、Eloquentコレクションクラスは、Eloquentコレクション操作に特化したいくつかの追加メソッドも提供しています。In addition to the methods provided by Laravel's base collection class, the Eloquent collection class provides a few extra methods[/docs/{{version}}/eloquent-collections#available-methods] that are specifically intended for interacting with collections of Eloquent models.
LaravelのコレクションはすべてPHPのiterableなインターフェイスを実装しているため、コレクションを配列のようにループ処理できます。Since all of Laravel's collections implement PHP's iterable interfaces, you may loop over collections as if they were an array:
foreach ($flights as $flight) {
echo $flight->name;
}
結果の分割Chunking Results
all
またはget
メソッドを使用して数万のEloquentレコードを読み込もうとすると、アプリケーションのメモリを不足させる可能性があります。これらのメソッドを使用する代わりに、chunk
メソッドを使用して、多数のモデルをより効率的に処理してください。Your application may run out of memory if you attempt to load tens of thousands of Eloquent records via the all
or get
methods. Instead of using these methods, the chunk
method may be used to process large numbers of models more efficiently.
chunk
メソッドは、Eloquentモデルのサブセットを取得し、それらをクロージャに渡して処理します。Eloquentモデルの現在のチャンクのみ一度に取得されるため、chunk
メソッドを使用すると大量のモデルを操作するときに、メモリ使用量が大幅に削減できます。The chunk
method will retrieve a subset of Eloquent models, passing them to a closure for processing. Since only the current chunk of Eloquent models is retrieved at a time, the chunk
method will provide significantly reduced memory usage when working with a large number of models:
use App\Models\Flight;
use Illuminate\Database\Eloquent\Collection;
Flight::chunk(200, function (Collection $flights) {
foreach ($flights as $flight) {
// ...
}
});
chunk
メソッドに渡す最初の引数は、「チャンク」ごとに受信するレコード数です。2番目の引数として渡すクロージャは、データベースから取得したチャンクごとに呼び出されます。レコードのチャンクを取得しクロージャへ渡すために、毎回データベースクエリを実行します。The first argument passed to the chunk
method is the number of records you wish to receive per "chunk". The closure passed as the second argument will be invoked 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.
結果を反復処理するときに、更新するカラムに基づいてchunk
メソッドの結果をフィルタリングする場合は、chunkById
メソッドを使用する必要があります。こうしたシナリオでchunk
メソッドを使用すると、一貫性が無く予期しない結果を生じる可能性があります。内部的にchunkById
メソッドは常に、前のチャンクの最後のモデルよりも大きいid
カラムを持つモデルを取得します。If you are filtering the results of the chunk
method based on a column that you will also be updating while iterating over the results, you should use the chunkById
method. Using the chunk
method in these scenarios could lead to unexpected and inconsistent results. Internally, the chunkById
method will always retrieve models with an id
column greater than the last model in the previous chunk:
Flight::where('departed', true)
->chunkById(200, function (Collection $flights) {
$flights->each->update(['departed' => false]);
}, column: 'id');
chunkById
メソッドとlazyById
メソッドは、実行するクエリに独自の"Where"条件を追加するため、通常はクロージャの中へ独自の条件を論理的にグループ化する必要があります。Since the chunkById
and lazyById
methods add their own "where" conditions to the query being executed, you should typically logically group[/docs/{{version}}/queries#logical-grouping] your own conditions within a closure:
Flight::where(function ($query) {
$query->where('delayed', true)->orWhere('cancelled', true);
})->chunkById(200, function (Collection $flights) {
$flights->each->update([
'departed' => false,
'cancelled' => true
]);
}, column: 'id');
レイジーコレクションを使用する分割Chunking Using Lazy Collections
lazy
メソッドは、裏でチャンク単位でクエリを実行するという意味で、chunk
メソッドと同様に動作します。しかし、lazy
メソッドは、各チャンクをそのままコールバックへ渡すのではなく、フラット化したEloquentモデルのLazyCollection
を返すので、結果を単一のストリームとして操作できます。The lazy
method works similarly to the chunk
method[#chunking-results] in the sense that, behind the scenes, it executes the query in chunks. However, instead of passing each chunk directly into a callback as is, the lazy
method returns a flattened LazyCollection
[/docs/{{version}}/collections#lazy-collections] of Eloquent models, which lets you interact with the results as a single stream:
use App\Models\Flight;
foreach (Flight::lazy() as $flight) {
// ...
}
もし、lazy
メソッドの結果を、結果の反復処理中に更新されるカラムに基づいてフィルタリングするのであれば、lazyById
メソッドを使うべきです。内部的には、lazyById
メソッドは、id
カラムが前のチャンクの最後のモデルよりも大きいモデルを常に取得します。If you are filtering the results of the lazy
method based on a column that you will also be updating while iterating over the results, you should use the lazyById
method. Internally, the lazyById
method will always retrieve models with an id
column greater than the last model in the previous chunk:
Flight::where('departed', true)
->lazyById(200, column: 'id')
->each->update(['departed' => false]);
lazyByIdDesc
メソッドを使って、id
の降順に基づいて結果をフィルタリングできます。You may filter the results based on the descending order of the id
using the lazyByIdDesc
method.
カーソルCursors
lazy
メソッドと同様に、cursor
メソッドを使用すると、何万ものEloquentモデルのレコードを反復処理する際に、アプリケーションのメモリ消費量を大幅に削減できます。Similar to the lazy
method, the cursor
method may be used to significantly reduce your application's memory consumption when iterating through tens of thousands of Eloquent model records.
cursor
メソッドは単一のデータベースクエリのみを実行します。ただし、個々のEloquentモデルは、実際の繰り返し処理までハイドレートされません。したがって、カーソルを反復処理している間、常に1つのEloquentモデルのみがメモリに保持されます。The cursor
method will only execute a single database query; however, the individual Eloquent models will not be hydrated until they are actually iterated over. Therefore, only one Eloquent model is kept in memory at any given time while iterating over the cursor.
Warning!
cursor
メソッドは一度に1つのEloquentモデルしかメモリに保持しないため、リレーションをEagerロードできません。リレーションシップをEagerロードする必要がある場合は、代わりにlazy
メソッド の使用を検討してください。[!WARNING]
Since thecursor
method only ever holds a single Eloquent model in memory at a time, it cannot eager load relationships. If you need to eager load relationships, consider using thelazy
method[#chunking-using-lazy-collections] instead.
内部的には、cursor
メソッドはPHPのジェネレータを使ってこの機能を実装しています。Internally, the cursor
method uses PHP generators[https://www.php.net/manual/en/language.generators.overview.php] to implement this functionality:
use App\Models\Flight;
foreach (Flight::where('destination', 'Zurich')->cursor() as $flight) {
// ...
}
cursor
はIlluminate\Support\LazyCollection
インスタンスを返します。レイジーコレクションを使用すると、一度に1つのモデルのみをメモリにロードしながら、一般的なLaravelコレクションで使用できる多くのコレクションメソッドを使用できます。The cursor
returns an Illuminate\Support\LazyCollection
instance. Lazy collections[/docs/{{version}}/collections#lazy-collections] allow you to use many of the collection methods available on typical Laravel collections while only loading a single model into memory at a time:
use App\Models\User;
$users = User::cursor()->filter(function (User $user) {
return $user->id > 500;
});
foreach ($users as $user) {
echo $user->id;
}
cursor
メソッドは、通常のクエリよりもはるかに少ないメモリしか使用しませんが(一度に1つのEloquentモデルをメモリ内に保持するだけです)、それでも最終的にはメモリが不足するでしょう。これは、PHPのPDOドライバが、素のクエリ結果をすべてバッファに内部的にキャッシュしているためです。非常に多くのEloquentレコードを扱う場合には、代わりにlazy
メソッドの使用を検討してください。Although the cursor
method uses far less memory than a regular query (by only holding a single Eloquent model in memory at a time), it will still eventually run out of memory. This is due to PHP's PDO driver internally caching all raw query results in its buffer[https://www.php.net/manual/en/mysqlinfo.concepts.buffering.php]. If you're dealing with a very large number of Eloquent records, consider using the lazy
method[#chunking-using-lazy-collections] instead.
上級サブクエリAdvanced Subqueries
サブクエリのSELECTSubquery Selects
Eloquentは、高度なサブクエリサポートも提供します。これにより、単一のクエリで関連するテーブルから情報を取得できます。たとえば、フライトの「目的地」のテーブルと目的地への「フライト」のテーブルがあるとします。flights
テーブルには、フライトが目的地に到着した時刻を示すarrived_at
列が含まれています。Eloquent also offers advanced subquery support, which allows you to pull information from related tables in a single query. For example, let's imagine that we have a table of flight destinations
and a table of flights
to destinations. The flights
table contains an arrived_at
column which indicates when the flight arrived at the destination.
クエリビルダのselect
メソッドとaddSelect
メソッドで使用できるサブクエリ機能を使用すると、1つのクエリを使用して、すべてのdestinations
とその目的地に最近到着したフライトの名前を選択できます。Using the subquery functionality available to the query builder's select
and addSelect
methods, we can select all of the destinations
and the name of the flight that most recently arrived at that destination using a single query:
use App\Models\Destination;
use App\Models\Flight;
return Destination::addSelect(['last_flight' => Flight::select('name')
->whereColumn('destination_id', 'destinations.id')
->orderByDesc('arrived_at')
->limit(1)
])->get();
サブクエリの順序Subquery Ordering
さらに、クエリビルダのorderBy
関数はサブクエリをサポートします。フライトの例を引き続き使用すると、この機能を使用して、最後のフライトが目的地へ到着した日時に基づいて、すべての目的地を並べ替えることができます。繰り返しますが、これは単一のデータベースクエリの実行中に実行できます。In addition, the query builder's orderBy
function supports subqueries. Continuing to use our flight example, we may use this functionality to sort all destinations based on when the last flight arrived at that destination. Again, this may be done while executing a single database query:
return Destination::orderByDesc(
Flight::select('arrived_at')
->whereColumn('destination_id', 'destinations.id')
->orderByDesc('arrived_at')
->limit(1)
)->get();
単一モデル/集計の取得Retrieving Single Models / Aggregates
特定のクエリに一致するすべてのレコードを取得することに加えて、find
、first
、またはfirstWhere
メソッドを使用して単一のレコードを取得することもできます。モデルのコレクションを返す代わりに、これらのメソッドは単一のモデルインスタンスを返します。In addition to retrieving all of the records matching a given query, you may also retrieve single records using the find
, first
, or firstWhere
methods. Instead of returning a collection of models, these methods return a single model instance:
use App\Models\Flight;
// 主キーでモデルを取得
$flight = Flight::find(1);
// クエリの制約に一致する最初のモデルを取得
$flight = Flight::where('active', 1)->first();
// クエリの制約に一致する最初のモデルを取得する別の記法
$flight = Flight::firstWhere('active', 1);
結果が見つからない場合は、別のアクションを実行したいこともあります。findOr
とfirstOr
メソッドは単一のモデルインスタンスを返しますが、結果が見つからなかった場合は指定クロージャを実行します。クロージャの返却値は、メソッドの結果とみなします。Sometimes you may wish to perform some other action if no results are found. The findOr
and firstOr
methods will return a single model instance or, if no results are found, execute the given closure. The value returned by the closure will be considered the result of the method:
$flight = Flight::findOr(1, function () {
// ...
});
$flight = Flight::where('legs', '>', 3)->firstOr(function () {
// ...
});
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, an Illuminate\Database\Eloquent\ModelNotFoundException
will be thrown:
$flight = Flight::findOrFail(1);
$flight = Flight::where('legs', '>', 3)->firstOrFail();
ModelNotFoundException
をキャッチしない場合は、404 HTTPレスポンスをクライアントへ自動的に返送します。If the ModelNotFoundException
is not caught, a 404 HTTP response is automatically sent back to the client:
use App\Models\Flight;
Route::get('/api/flights/{id}', function (string $id) {
return Flight::findOrFail($id);
});
モデルの取得/生成Retrieving or Creating Models
firstOrCreate
メソッドは、指定したカラムと値のペアを使用してデータベースレコードを見つけようとします。モデルがデータベースで見つからない場合は、最初の配列引数をオプションの2番目の配列引数とマージした結果の属性を含むレコードが挿入されます。The firstOrCreate
method will attempt to locate a database record using the given column / value pairs. If the model cannot be found in the database, a record will be inserted with the attributes resulting from merging the first array argument with the optional second array argument:
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 manually call the save
method to persist it:
use App\Models\Flight;
// 名前でフライトを取得するか、存在しない場合は作成
$flight = Flight::firstOrCreate([
'name' => 'London to Paris'
]);
// 名前でフライトを取得するか、name、delayed、arrival_time属性を使用してフライトを作成
$flight = Flight::firstOrCreate(
['name' => 'London to Paris'],
['delayed' => 1, 'arrival_time' => '11:30']
);
// 名前でフライトを取得するか、新しいFlightインスタンスをインスタンス化
$flight = Flight::firstOrNew([
'name' => 'London to Paris'
]);
// 名前でフライトを取得するか、name、delayed、arrival_time属性を使用してインスタンス化
$flight = Flight::firstOrNew(
['name' => 'Tokyo to Sydney'],
['delayed' => 1, 'arrival_time' => '11:30']
);
集計の取得Retrieving Aggregates
Eloquentモデルを操作するときは、Laravel クエリビルダが提供するcount
、sum
、max
、およびその他の集計メソッドを使用することもできます。ご想像のとおり、これらのメソッドは、Eloquentモデルインスタンスの代わりにスカラー値を返します。When interacting with Eloquent models, you may also use the count
, sum
, max
, and other aggregate methods[/docs/{{version}}/queries#aggregates] provided by the Laravel query builder[/docs/{{version}}/queries]. As you might expect, these methods return a scalar value instead of an Eloquent model instance:
$count = Flight::where('active', 1)->count();
$max = Flight::where('active', 1)->max('price');
モデルの挿入と更新Inserting and Updating Models
挿入Inserts
もちろん、Eloquentを使用する状況は、データベースからモデルを取得する必要がある場合だけに限りません。新しいレコードを挿入する必要もあるでしょう。うれしいことに、Eloquentはこれをシンプルにします。データベースへ新しいレコードを挿入するには、新しいモデルインスタンスをインスタンス化し、モデルに属性をセットする必要があります。次に、モデルインスタンスでsave
メソッドを呼び出します。Of course, when using Eloquent, we don't only need to retrieve models from the database. We also need to insert new records. Thankfully, Eloquent makes it simple. To insert a new record into the database, you should instantiate a new model instance and set attributes on the model. Then, call the save
method on the model instance:
<?php
namespace App\Http\Controllers;
use App\Http\Controllers\Controller;
use App\Models\Flight;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class FlightController extends Controller
{
/**
* 新しいフライトをデータベースに保存
*/
public function store(Request $request): RedirectResponse
{
// リクエストのバリデーション処理…
$flight = new Flight;
$flight->name = $request->name;
$flight->save();
return redirect('/flights');
}
}
この例では、受信HTTPリクエストのname
フィールドをApp\Models\Flight
モデルインスタンスのname
属性に割り当てます。save
メソッドを呼び出すと、レコードがデータベースに挿入されます。モデルのcreated_at
およびupdated_at
タイムスタンプは、save
メソッドが呼び出されたときに自動的に設定されるため、手作業で設定する必要はありません。In this example, we assign the name
field from the incoming HTTP request to the name
attribute of the App\Models\Flight
model instance. When we call the save
method, a record will be inserted into the database. The model's 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.
もしくは、create
メソッドを使用して、単一のPHPステートメントにより、新しいモデルを「保存」することもできます。create
メソッドは、その挿入したモデルインスタンスを返します。Alternatively, you may use the create
method to "save" a new model using a single PHP statement. The inserted model instance will be returned to you by the create
method:
use App\Models\Flight;
$flight = Flight::create([
'name' => 'London to Paris',
]);
ただし、create
メソッドを使用する前に、モデルクラスでfillable
またはguarded
プロパティを指定する必要があります。すべてのEloquentモデルはデフォルトで複数代入の脆弱性から保護されているため、こうしたプロパティが必須なのです。複数代入の詳細については、複数代入のドキュメントを参照してください。However, before using the create
method, you will need to specify either a fillable
or guarded
property on your model class. These properties are required because all Eloquent models are protected against mass assignment vulnerabilities by default. To learn more about mass assignment, please consult the mass assignment documentation[#mass-assignment].
更新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 and set any attributes you wish to update. Then, you should call the model's save
method. Again, the updated_at
timestamp will automatically be updated, so there is no need to manually set its value:
use App\Models\Flight;
$flight = Flight::find(1);
$flight->name = 'Paris to London';
$flight->save();
既存のモデルを更新する時に、一致するモデルが存在しない場合は、新しいモデルを作成したい場合もあるでしょう。firstOrCreate
メソッドと同様に、updateOrCreate
メソッドはモデルを永続化するため、手作業でsave
メソッドを呼び出す必要はありません。Occasionally, you may need to update an existing model or create a new model if no matching model exists. Like the firstOrCreate
method, the updateOrCreate
method persists the model, so there's no need to manually call the save
method.
以下の例では、Oakland
が「出発地(departure
)」で、San Diego
が「目的地(destination
)」のフライトが存在する場合、その「価格(price
)」カラムと「割引(discounted
)」カラムが更新されます。該当するフライトが存在しない場合は、最初の引数配列を2番目の引数配列とマージした結果の属性を持つ新しいフライトが作成されます。In the example below, if a flight exists with a departure
location of Oakland
and a destination
location of San Diego
, its price
and discounted
columns will be updated. If no such flight exists, a new flight will be created which has the attributes resulting from merging the first argument array with the second argument array:
$flight = Flight::updateOrCreate(
['departure' => 'Oakland', 'destination' => 'San Diego'],
['price' => 99, 'discounted' => 1]
);
複数更新Mass Updates
特定のクエリに一致するモデルに対して更新を実行することもできます。この例では、「アクティブ(active
)」でdestination
がSan Diego
のすべてのフライトが遅延(delayed)としてマークされます。Updates can also be performed against 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:
Flight::where('active', 1)
->where('destination', 'San Diego')
->update(['delayed' => 1]);
update
メソッドは、更新する必要のあるカラムを表すカラム名と値のペアの配列を引数に取ります。update
メソッドは、影響を受けた行数を返します。The update
method expects an array of column and value pairs representing the columns that should be updated. The update
method returns the number of affected rows.
Warning! Eloquentを介して一括更新を発行する場合、更新されたモデルに対して、
saving
、saved
、updating
、updated
モデルイベントは発生しません。これは一括更新を実行する場合に、モデルが実際には取得されないからです。[!WARNING]
When issuing a mass update via Eloquent, thesaving
,saved
,updating
, andupdated
model events will not be fired for the updated models. This is because the models are never actually retrieved when issuing a mass update.
属性の変更の判断Examining Attribute Changes
Eloquentでは、isDirty
、isClean
、wasChanged
メソッドを提供しており、モデルの内部状態を調べ、モデルが最初に取得されたときからその属性がどのように変更されたかを判別できます。Eloquent provides the isDirty
, isClean
, and wasChanged
methods to examine the internal state of your model and determine how its attributes have changed from when the model was originally retrieved.
isDirty
メソッドは、モデル取得後にそのモデルの属性が変更されたかを判定します。isDirty
メソッドに特定の属性名、あるいは属性の配列を渡せば、いずれかの属性に変更があったかを判定できます。isClean
メソッドは、モデル取得後、属性が変更されていないことを判定します。このメソッドはオプションのattribute引数も受け付けます。The isDirty
method determines if any of the model's attributes have been changed since the model was retrieved. You may pass a specific attribute name or an array of attributes to the isDirty
method to determine if any of the attributes are "dirty". The isClean
method will determine if an attribute has remained unchanged since the model was retrieved. This method also accepts an optional attribute argument:
use App\Models\User;
$user = User::create([
'first_name' => 'Taylor',
'last_name' => 'Otwell',
'title' => 'Developer',
]);
$user->title = 'Painter';
$user->isDirty(); // true
$user->isDirty('title'); // true
$user->isDirty('first_name'); // false
$user->isDirty(['first_name', 'title']); // true
$user->isClean(); // false
$user->isClean('title'); // false
$user->isClean('first_name'); // true
$user->isClean(['first_name', 'title']); // false
$user->save();
$user->isDirty(); // false
$user->isClean(); // true
wasChanged
メソッドは現在のリクエストサイクル内で、モデルの最後の保存時に、属性に変更が起きたかを判別します。必要に応じ属性名を渡して、その属性に変更が発生したか確認できます。The wasChanged
method determines if any attributes were changed when the model was last saved within the current request cycle. If needed, you may pass an attribute name to see if a particular attribute was changed:
$user = User::create([
'first_name' => 'Taylor',
'last_name' => 'Otwell',
'title' => 'Developer',
]);
$user->title = 'Painter';
$user->save();
$user->wasChanged(); // true
$user->wasChanged('title'); // true
$user->wasChanged(['title', 'slug']); // true
$user->wasChanged('first_name'); // false
$user->wasChanged(['first_name', 'title']); // true
getOriginal
メソッドは、モデル取得後の変更操作と関係なく、モデルの元の属性を含む配列を返します。必要に応じて、特定の属性名を渡し、その属性の元の値を取得できます。The getOriginal
method returns an array containing the original attributes of the model regardless of any changes to the model since it was retrieved. If needed, you may pass a specific attribute name to get the original value of a particular attribute:
$user = User::find(1);
$user->name; // John
$user->email; // john@example.com
$user->name = "Jack";
$user->name; // Jack
$user->getOriginal('name'); // John
$user->getOriginal(); // 元の属性の配列
複数代入Mass Assignment
create
メソッドを使用して、単一PHPステートメントで新しいモデルを「保存」できます。挿入したモデルインスタンスが、このメソッドにより返されます。You may use the create
method to "save" a new model using a single PHP statement. The inserted model instance will be returned to you by the method:
use App\Models\Flight;
$flight = Flight::create([
'name' => 'London to Paris',
]);
ただし、create
メソッドを使用する前に、モデルクラスでfillable
またはguarded
プロパティを指定する必要があります。すべてのEloquentモデルはデフォルトで複数代入の脆弱性から保護されているため、こうしたプロパティが必須になります。However, before using the create
method, you will need to specify either a fillable
or guarded
property on your model class. These properties are required because all Eloquent models are protected against mass assignment vulnerabilities by default.
複数代入の脆弱性は、ユーザーから予期していないHTTPリクエストフィールドを渡され、そのフィールドがデータベース内の予想外のカラムを変更する場合に発生します。たとえば、悪意のあるユーザーがHTTPリクエストを介してis_admin
パラメータを送信し、それがモデルのcreate
メソッドに渡されて、ユーザーが自分自身を管理者に格上げする場合が考えられます。A mass assignment vulnerability occurs when a user passes an unexpected HTTP request field and that field changes a column in your database that you did not expect. For example, a malicious user might send an is_admin
parameter through an HTTP request, which is then passed to your model's create
method, allowing the user to escalate themselves to an administrator.
したがって、Eloquentを使い始めるには、複数代入可能にするモデル属性を定義する必要があります。これは、モデルの$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\Models;
use Illuminate\Database\Eloquent\Model;
class Flight extends Model
{
/**
* 複数代入可能な属性
*
* @var array<int, string>
*/
protected $fillable = ['name'];
}
複数代入可能な属性を指定したら、create
メソッドを使用してデータベースに新しいレコードを挿入できます。create
メソッドは、新しく作成したモデルインスタンスを返します。Once you have specified which attributes are mass assignable, you may use the create
method to insert a new record in the database. The create
method returns the newly created model instance:
$flight = Flight::create(['name' => 'London to Paris']);
モデルインスタンスがすでにある場合は、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' => 'Amsterdam to Frankfurt']);
一括割り当てとJSONカラムMass Assignment and JSON Columns
JSONカラムへ代入するときは、各カラムの複数代入可能キーをモデルの$fillable
配列で指定する必要があります。セキュリティのため、Laravelはguarded
プロパティを使用する場合のネストしたJSON属性の更新をサポートしていません。When assigning JSON columns, each column's mass assignable key must be specified in your model's $fillable
array. For security, Laravel does not support updating nested JSON attributes when using the guarded
property:
/**
* 複数代入可能な属性
*
* @var array<int, string>
*/
protected $fillable = [
'options->enabled',
];
複数代入の許可Allowing Mass Assignment
すべての属性を一括割り当て可能にしたい場合は、モデルの$guarded
プロパティを空の配列として定義します。モデルの保護を解除する場合は、Eloquentのfill
、create
、およびupdate
メソッドに渡たす配列へいちいち特別な注意を払う必要があります。If you would like to make all of your attributes mass assignable, you may define your model's $guarded
property as an empty array. If you choose to unguard your model, you should take special care to always hand-craft the arrays passed to Eloquent's fill
, create
, and update
methods:
/**
* 複数代入不可能な属性
*
* @var array<string>|bool
*/
protected $guarded = [];
複数代入例外Mass Assignment Exceptions
複数代入操作を行うときデフォルトで、$fillable
配列に含まれない属性は黙って破棄されます。実稼働環境でこれは期待されている動作です。しかし、ローカル開発時では、なぜモデルの変更が反映されないのか混乱させる可能性があります。By default, attributes that are not included in the $fillable
array are silently discarded when performing mass-assignment operations. In production, this is expected behavior; however, during local development it can lead to confusion as to why model changes are not taking effect.
必要であれば、preventSilentlyDiscardingAttributes
メソッドを呼び出し、複数代入不可の属性へ代入しようとした時に例外を投げるようにLaravelへ指示できます。通常、このメソッドはアプリケーションのAppServiceProvider
クラスのboot
メソッドで呼び出します。If you wish, you may instruct Laravel to throw an exception when attempting to fill an unfillable attribute by invoking the preventSilentlyDiscardingAttributes
method. Typically, this method should be invoked in the boot
method of your application's AppServiceProvider
class:
use Illuminate\Database\Eloquent\Model;
/**
* 全アプリケーションサービスの初期起動処理
*/
public function boot(): void
{
Model::preventSilentlyDiscardingAttributes($this->app->isLocal());
}
更新/挿入Upserts
Eloquentのupsert
メソッドを使用すると、単一で極小の操作でレコードを更新または作成できます。メソッドの最初の引数は挿入または更新する値で構成され、2番目の引数は関連テーブル内のレコードを一意に識別するカラムのリストです。メソッドの最後の引数である3番目の引数は、データベースに一致するレコードが既に存在する場合に更新するカラムの配列です。モデルでタイムスタンプが有効になっている場合、upsert
メソッドは自動的にcreated_at
とupdated_at
のタイムスタンプを設定します。Eloquent's upsert
method may be used to update or create records in a single, atomic operation. The method's first argument consists of the values to insert or update, while the second argument lists the column(s) that uniquely identify records within the associated table. The method's third and final argument is an array of the columns that should be updated if a matching record already exists in the database. The upsert
method will automatically set the created_at
and updated_at
timestamps if timestamps are enabled on the model:
Flight::upsert([
['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
], uniqueBy: ['departure', 'destination'], update: ['price']);
Warning! SQL Server以外のすべてのデータベースでは、
upsert
メソッドの第2引数のカラムへ"primary"、または"unique"インデックスを指定する必要があります。さらに、MariaDBとMySQLデータベースドライバは、upsert
メソッドの第2引数を無視し、常にテーブルの"primary"および"unique"インデックスを既存レコードの検出に使用します。[!WARNING]
All databases except SQL Server require the columns in the second argument of theupsert
method to have a "primary" or "unique" index. In addition, the MariaDB and MySQL database drivers ignore the second argument of theupsert
method and always use the "primary" and "unique" indexes of the table to detect existing records.
モデルの削除Deleting Models
モデルを削除するには、モデルインスタンスでdelete
メソッドを呼び出してください。To delete a model, you may call the delete
method on the model instance:
use App\Models\Flight;
$flight = Flight::find(1);
$flight->delete();
モデルに関連しているすべてのデータベースレコードを削除するには、truncate
メソッドを呼びだせます。truncate
操作は、モデルの関連テーブルの自動増分IDをリセットします。You may call the truncate
method to delete all of the model's associated database records. The truncate
operation will also reset any auto-incrementing IDs on the model's associated table:
Flight::truncate();
主キーによる既存のモデルの削除Deleting an Existing Model by its Primary Key
上記の例では、delete
メソッドを呼び出す前にデータベースからモデルを取得しています。しかし、モデルの主キーがわかっている場合は、destroy
メソッドを呼び出して、モデルを明示的に取得せずにモデルを削除できます。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 explicitly retrieving it by calling the destroy
method. In addition to accepting the single primary key, the destroy
method will accept multiple primary keys, an array of primary keys, or a collection[/docs/{{version}}/collections] of primary keys:
Flight::destroy(1);
Flight::destroy(1, 2, 3);
Flight::destroy([1, 2, 3]);
Flight::destroy(collect([1, 2, 3]));
モデルのソフトデリートを利用している場合は、forceDestroy
メソッドを使ってモデルを完全に削除できます。If you are utilizing soft deleting models[#soft-deleting], you may permanently delete models via the forceDestroy
method:
Flight::forceDestroy(1);
Warning!
destroy
メソッドは各モデルを個別にロードし、delete
メソッドを呼び出して、deleting
イベントとdeleted
イベントが各モデルに適切にディスパッチされるようにします。[!WARNING]
Thedestroy
method loads each model individually and calls thedelete
method so that thedeleting
anddeleted
events are properly dispatched for each model.
クエリを使用したモデルの削除Deleting Models Using Queries
もちろん、Eloquentクエリを作成して、クエリの条件に一致するすべてのモデルを削除することもできます。この例では、非アクティブとしてマークされているすべてのフライトを削除します。一括更新と同様に、一括削除では、削除されたモデルのモデルイベントはディスパッチされません。Of course, you may build an Eloquent query to delete all models matching your query's criteria. In this example, we will delete all flights that are marked as inactive. Like mass updates, mass deletes will not dispatch model events for the models that are deleted:
$deleted = Flight::where('active', 0)->delete();
Warning! Eloquentを介して一括削除ステートメントを実行すると、削除されたモデルに対して
deleting
およびdeleted
モデルイベントがディスパッチされません。これは、deleteステートメントの実行時にモデルが実際には取得されないためです。[!WARNING]
When executing a mass delete statement via Eloquent, thedeleting
anddeleted
model events will not be dispatched for the deleted models. This is because the models are never actually retrieved when executing the delete statement.
ソフトデリートSoft Deleting
Eloquentは、データベースから実際にレコードを削除するだけでなく、モデルを「ソフトデリート」することもできます。モデルがソフトデリートされても、実際にはデータベースから削除されません。代わりに、モデルに「deleted_at」属性がセットされ、モデルを「削除」した日時が保存されます。モデルのソフトデリートを有効にするには、Illuminate\Database\Eloquent\SoftDeletes
トレイトをモデルに追加します。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 indicating the date and time at which the model was "deleted". To enable soft deletes for a model, add the Illuminate\Database\Eloquent\SoftDeletes
trait to the model:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
class Flight extends Model
{
use SoftDeletes;
}
Note:
SoftDeletes
トレイトは、deleted_at
属性をDateTime
/Carbon
インスタンスに自動的にキャストします。[!NOTE]
TheSoftDeletes
trait will automatically cast thedeleted_at
attribute to aDateTime
/Carbon
instance for you.
データベーステーブルにdeleted_at
カラムを追加する必要があります。Laravelスキーマビルダはこのカラムを作成するためのヘルパメソッドを用意しています。You should also add the deleted_at
column to your database table. The Laravel schema builder[/docs/{{version}}/migrations] contains a helper method to create this column:
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
Schema::table('flights', function (Blueprint $table) {
$table->softDeletes();
});
Schema::table('flights', function (Blueprint $table) {
$table->dropSoftDeletes();
});
これで、モデルの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. However, the model's database record will be left in the table. 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, you may use the trashed
method:
if ($flight->trashed()) {
// ...
}
ソフトデリートしたモデルの復元Restoring Soft Deleted Models
ソフトデリートしたモデルを「削除解除」したい場合もあるでしょう。ソフトデリートしたモデルを復元するには、モデルインスタンスのrestore
メソッドを呼び出します。restore
メソッドは、モデルのdeleted_at
カラムをnull
にセットします。Sometimes you may wish to "un-delete" a soft deleted model. To restore a soft deleted model, you may call the restore
method on a model instance. The restore
method will set the model's deleted_at
column to null
:
$flight->restore();
クエリでrestore
メソッドを使用して、複数のモデルを復元することもできます。繰り返しますが、他の「複数」操作と同様に、これは復元されたモデルのモデルイベントをディスパッチしません。You may also use the restore
method in a query to restore multiple models. Again, like other "mass" operations, this will not dispatch any model events for the models that are restored:
Flight::withTrashed()
->where('airline_id', 1)
->restore();
restore
メソッドは、リレーションのクエリを作成するときにも使用できます。The restore
method may also be used when building relationship[/docs/{{version}}/eloquent-relationships] queries:
$flight->history()->restore();
モデルの完全な削除Permanently Deleting Models
データベースからモデルを本当に削除する必要が起きる場合もあるでしょう。forceDelete
メソッドを使用して、データベーステーブルからソフトデリートされたモデルを完全に削除できます。Sometimes you may need to truly remove a model from your database. You may use the forceDelete
method to permanently remove a soft deleted model from the database table:
$flight->forceDelete();
Eloquentリレーションクエリを作成するときに、forceDelete
メソッドを使用することもできます。You may also use the forceDelete
method when building Eloquent relationship queries:
$flight->history()->forceDelete();
ソフトデリート済みモデルのクエリ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 be included in a query's results by calling the withTrashed
method on the query:
use App\Models\Flight;
$flights = Flight::withTrashed()
->where('account_id', 1)
->get();
withTrashed
メソッドは、リレーションクエリを作成するときにも呼び出すことができます。The withTrashed
method may also be called when building 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 = Flight::onlyTrashed()
->where('airline_id', 1)
->get();
モデルの整理Pruning Models
不要になったモデルを定期的に削除したい場合があります。これを実現するには、定期的に整理したいモデルに、Illuminate\Database\Eloquent\Prunable
かIlluminate\Database\Eloquent\MassPrunable
トレイトを追加してください。モデルにどちらかのトレイトを追加したら、不要なモデルを指定するEloquentのクエリビルダを返すprunable
メソッドを実装します。Sometimes you may want to periodically delete models that are no longer needed. To accomplish this, you may add the Illuminate\Database\Eloquent\Prunable
or Illuminate\Database\Eloquent\MassPrunable
trait to the models you would like to periodically prune. After adding one of the traits to the model, implement a prunable
method which returns an Eloquent query builder that resolves the models that are no longer needed:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Prunable;
class Flight extends Model
{
use Prunable;
/**
* 整理可能モデルクエリの取得
*/
public function prunable(): Builder
{
return static::where('created_at', '<=', now()->subMonth());
}
}
Prunable
としてモデルを作成する際に、そのモデルへpruning
メソッドを定義することもできます。このメソッドはモデルが削除される前に呼び出されます。このメソッドは、モデルがデータベースから永久に削除される前に、保存しているファイルなど、モデルに関連する追加リソースを削除するために役立ちます。When marking models as Prunable
, you may also define a pruning
method on the model. This method will be called before the model is deleted. This method can be useful for deleting any additional resources associated with the model, such as stored files, before the model is permanently removed from the database:
/**
* 整理可能モデルの準備
*/
protected function pruning(): void
{
// ...
}
整理可能なモデルを設定した後、アプリケーションのroutes/console.php
ファイルでmodel:prune
Artisanコマンドをスケジュールする必要があります。このコマンドを実行する適切な間隔は自由に選べます。After configuring your prunable model, you should schedule the model:prune
Artisan command in your application's routes/console.php
file. You are free to choose the appropriate interval at which this command should be run:
use Illuminate\Support\Facades\Schedule;
Schedule::command('model:prune')->daily();
model:prune
コマンドは、裏でアプリケーションのapp/Models
ディレクトリ内にある、"Prunable"モデルを自動的に検出します。モデルが別の場所にある場合は、--model
オプションを使って、モデルクラス名を指定できます。Behind the scenes, the model:prune
command will automatically detect "Prunable" models within your application's app/Models
directory. If your models are in a different location, you may use the --model
option to specify the model class names:
Schedule::command('model:prune', [
'--model' => [Address::class, Flight::class],
])->daily();
検出したすべてのモデルを整理する場合に、特定のモデルを除外したい場合は、--except
オプションを使用します。If you wish to exclude certain models from being pruned while pruning all other detected models, you may use the --except
option:
Schedule::command('model:prune', [
'--except' => [Address::class, Flight::class],
])->daily();
model:prune
コマンドを--pretend
オプション付きで実行することで、prunable
クエリをテストできます。このオプションを付けると、model:prune
コマンドが実際にコマンドを実行する場合、いくつのレコードを整理するかだけを報告します。You may test your prunable
query by executing the model:prune
command with the --pretend
option. When pretending, the model:prune
command will simply report how many records would be pruned if the command were to actually run:
php artisan model:prune --pretend
Warning! Prunableクエリに一致した場合、ソフトデリートするモデルでも、永久的に削除(
forceDelete
)します。[!WARNING]
Soft deleting models will be permanently deleted (forceDelete
) if they match the prunable query.
複数整理Mass Pruning
モデルへIlluminate\Database\Eloquent\MassPrunable
トレイトが付与されると、モデルは複数削除クエリを使ってデータベースから削除されます。そのため、pruning
メソッドを呼び出しませんし、deleting
やdeleted
のモデルイベントも発行しません。これはモデルの削除前で実際に取得しないため、整理処理をより効率的に行うことができるからです。When models are marked with the Illuminate\Database\Eloquent\MassPrunable
trait, models are deleted from the database using mass-deletion queries. Therefore, the pruning
method will not be invoked, nor will the deleting
and deleted
model events be dispatched. This is because the models are never actually retrieved before deletion, thus making the pruning process much more efficient:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\MassPrunable;
class Flight extends Model
{
use MassPrunable;
/**
* 整理可能モデルクエリの取得
*/
public function prunable(): Builder
{
return static::where('created_at', '<=', now()->subMonth());
}
}
モデルの複製Replicating Models
replicate
メソッドを使用して、既存のモデルインスタンスの未保存のコピーを作成できます。この方法は、同じ属性を多く共有するモデルインスタンスがある場合にとくに役立ちます。You may create an unsaved copy of an existing model instance using the replicate
method. This method is particularly useful when you have model instances that share many of the same attributes:
use App\Models\Address;
$shipping = Address::create([
'type' => 'shipping',
'line_1' => '123 Example Street',
'city' => 'Victorville',
'state' => 'CA',
'postcode' => '90001',
]);
$billing = $shipping->replicate()->fill([
'type' => 'billing'
]);
$billing->save();
1つ以上の属性を新しいモデルへ複製しないためには、配列をreplicate
メソッドへ渡します。To exclude one or more attributes from being replicated to the new model, you may pass an array to the replicate
method:
$flight = Flight::create([
'destination' => 'LAX',
'origin' => 'LHR',
'last_flown' => '2020-03-04 11:00:00',
'last_pilot_id' => 747,
]);
$flight = $flight->replicate([
'last_flown',
'last_pilot_id'
]);
クエリスコープ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 retrieve "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.
スコープの生成Generating Scopes
新しいグローバルスコープを生成するには、make:scope
Artisanコマンドを呼び出してください。生成したスコープは、アプリケーションのapp/Models/Scopes
ディレクトリへ設置します。To generate a new global scope, you may invoke the make:scope
Artisan command, which will place the generated scope in your application's app/Models/Scopes
directory:
php artisan make:scope AncientScope
グローバルスコープの作成Writing Global Scopes
グローバルスコープを書くのは簡単です。まず、make:scope
コマンドを使いIlluminate\Database\Eloquent\Scope
インターフェイスを実装したクラスを生成します。Scope
インターフェイスは、apply
メソッド1つの実装を求めています。必要に応じapply
メソッドへ、where
制約や他のタイプの句をクエリへ追加してください。Writing a global scope is simple. First, use the make:scope
command to generate a class that implements the Illuminate\Database\Eloquent\Scope
interface. The Scope
interface requires you to implement one method: apply
. The apply
method may add where
constraints or other types of clauses to the query as needed:
<?php
namespace App\Models\Scopes;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;
class AncientScope implements Scope
{
/**
* 指定のEloquentクエリビルダにスコープを適用
*/
public function apply(Builder $builder, Model $model): void
{
$builder->where('created_at', '<', now()->subYears(2000));
}
}
Note: グローバルスコープがクエリのSELECT句にカラムを追加する場合は、
select
の代わりにaddSelect
メソッドを使用する必要があります。これにより、クエリの既存のselect句が意図せず置き換えられるのを防ぐことができます。[!NOTE]
If your global scope is adding columns to the select clause of the query, you should use theaddSelect
method instead ofselect
. This will prevent the unintentional replacement of the query's existing select clause.
グローバルスコープの適用Applying Global Scopes
モデルにグローバルスコープを割り当てるには、モデルへScopedBy
アトリビュートを指定します。To assign a global scope to a model, you may simply place the ScopedBy
attribute on the model:
<?php
namespace App\Models;
use App\Models\Scopes\AncientScope;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;
#[ScopedBy([AncientScope::class])]
class User extends Model
{
//
}
あるいは、モデルのbooted
メソッドをオーバーライドして、モデルのaddGlobalScope
メソッドを呼び出せば、手作業でグローバルスコープを登録することも可能です。addGlobalScope
メソッドは、唯一スコープのインスタンスを引数に取ります。Or, you may manually register the global scope by overriding the model's booted
method and invoke the model's addGlobalScope
method. The addGlobalScope
method accepts an instance of your scope as its only argument:
<?php
namespace App\Models;
use App\Models\Scopes\AncientScope;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* モデルの"booted"メソッド
*/
protected static function booted(): void
{
static::addGlobalScope(new AncientScope);
}
}
上記の例のスコープをApp\Models\User
モデルに追加した後、User::all()
メソッドを呼び出すと、次のSQLクエリが実行されます。After adding the scope in the example above to the App\Models\User
model, a call to the User::all()
method will execute the following SQL query:
select * from `users` where `created_at` < 0021-02-18 00:00:00
匿名のグローバルスコープAnonymous Global Scopes
Eloquentはクロージャを使用してグローバルスコープを定義することもできます。クロージャを使用してグローバルスコープを定義する場合は、addGlobalScope
メソッドの第一引数に自分で選択したスコープ名を指定する必要があります。Eloquent also allows you to define global scopes using closures, which is particularly useful for simple scopes that do not warrant a separate class of their own. When defining a global scope using a closure, you should provide a scope name of your own choosing as the first argument to the addGlobalScope
method:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* モデルの"booted"メソッド
*/
protected static function booted(): void
{
static::addGlobalScope('ancient', function (Builder $builder) {
$builder->where('created_at', '<', now()->subYears(2000));
});
}
}
グローバルスコープの削除Removing Global Scopes
特定のクエリのグローバルスコープを削除する場合は、withoutGlobalScope
メソッドを使用できます。このメソッドは、グローバルスコープのクラス名だけを引数に取ります。If you would like to remove a global scope for a given query, you may use the withoutGlobalScope
method. This method accepts the class name of the global scope as its only argument:
User::withoutGlobalScope(AncientScope::class)->get();
もしくは、クロージャを使用してグローバルスコープを定義した場合は、グローバルスコープへ指定した文字列名を渡す必要があります。Or, if you defined the global scope using a closure, you should pass the string name that you assigned to the global scope:
User::withoutGlobalScope('ancient')->get();
クエリのグローバルスコープのいくつか、またはすべてを削除したい場合は、withoutGlobalScopes
メソッドを使用できます。If you would like to remove several or even all of the query's global scopes, you may use the withoutGlobalScopes
method:
// すべてのグローバルスコープを削除
User::withoutGlobalScopes()->get();
// グローバルスコープの一部を削除
User::withoutGlobalScopes([
FirstScope::class, SecondScope::class
])->get();
ローカルスコープLocal Scopes
ローカルスコープを使用すると、アプリケーション全体で簡単に再利用できる、共通のクエリ制約を定義できます。たとえば、「人気がある(popular)」と思われるすべてのユーザーを頻繁に取得する必要があるとしましょう。スコープを定義するには、Eloquentモデルメソッドの前にscope
を付けます。Local scopes allow you to define common sets of query 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
.
スコープは常に同じクエリビルダのインスタンスか、void
を返す必要があります。Scopes should always return the same query builder instance or void
:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 人気のあるユーザーのみを含むようにクエリのスコープを設定
*/
public function scopePopular(Builder $query): void
{
$query->where('votes', '>', 100);
}
/**
* アクティブユーザーのみを含むようにクエリのスコープを設定
*/
public function scopeActive(Builder $query): void
{
$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:
use App\Models\User;
$users = User::popular()->active()->orderBy('created_at')->get();
or
クエリ演算子を介して複数のEloquentモデルスコープを組み合わせるには、正しい論理グループ化を実現するためにクロージャを使用する必要のある場合があります。Combining multiple Eloquent model scopes via an or
query operator may require the use of closures to achieve the correct logical grouping[/docs/{{version}}/queries#logical-grouping]:
$users = User::popular()->orWhere(function (Builder $query) {
$query->active();
})->get();
ただし、これは面倒な場合があるため、Laravelは、クロージャを使用せずにスコープを流暢にチェーンできる「高次」の「orWhere」メソッドを提供しています。However, since this can be cumbersome, Laravel provides a "higher order" orWhere
method that allows you to fluently chain scopes together without the use of closures:
$users = User::popular()->orWhere->active()->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 method's signature. Scope parameters should be defined after the $query
parameter:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* 特定のタイプのユーザーのみを含むようにクエリのスコープを設定
*/
public function scopeOfType(Builder $query, string $type): void
{
$query->where('type', $type);
}
}
期待される引数をスコープメソッドの引数へ追加したら、スコープ呼び出し時に引数を渡すことができます。Once the expected arguments have been added to your scope method's signature, you may pass the arguments when calling the scope:
$users = User::ofType('admin')->get();
モデルの比較Comparing Models
2つのモデルが「同じ」であるかを判定する必要がある場合があるでしょう。2つのモデルに同じ主キー、テーブル、およびデータベース接続があるかどうかを手早く検証するために、is
とisNot
メソッドを使用できます。Sometimes you may need to determine if two models are the "same" or not. The is
and isNot
methods may be used to quickly verify two models have the same primary key, table, and database connection or not:
if ($post->is($anotherPost)) {
// ...
}
if ($post->isNot($anotherPost)) {
// ...
}
is
とisNot
メソッドは、belongsTo
、hasOne
、morphTo
、morphOne
リレーションを使用するときにも利用できます。このメソッドはそのモデルを取得するためにクエリを発行せず、関連モデルと比較したい場合、特に役立ちます。The is
and isNot
methods are also available when using the belongsTo
, hasOne
, morphTo
, and morphOne
relationships[/docs/{{version}}/eloquent-relationships]. This method is particularly helpful when you would like to compare a related model without issuing a query to retrieve that model:
if ($post->author()->is($user)) {
// ...
}
イベントEvents
モデル・イベント・ブロードキャストをチェックしてください。[!NOTE]
Note: Eloquentのイベントをクライアントサイドのアプリケーションへ直接ブロードキャストしたいですか?Laravelの
Want to broadcast your Eloquent events directly to your client-side application? Check out Laravel's model event broadcasting[/docs/{{version}}/broadcasting#model-broadcasting].
Eloquentモデルはいくつかのイベントをディスパッチし、モデルのライフサイクルの以下の瞬間をフックできるようにしています。:retrieved
、creating
、created
、updating
、updated
、saving
、saved
、deleting
、deleted
、trashed
、forceDeleting
、forceDeleted
、restoring
、restored
、replicating
。Eloquent models dispatch several events, allowing you to hook into the following moments in a model's lifecycle: retrieved
, creating
, created
, updating
, updated
, saving
, saved
, deleting
, deleted
, trashed
, forceDeleting
, forceDeleted
, restoring
, restored
, and replicating
.
retrieved
イベントは、既存のモデルをデータベースから取得したときにディスパッチします。新しいモデルをはじめて保存するときは、creating
イベントとcreated
イベントをディスパッチします。updating
/updated
イベントは、既存のモデルを変更し、save
メソッドが呼び出されたときにディスパッチします。saving
/saved
イベントは、モデルを作成または更新したときにディスパッチします。モデルの属性に変化がない場合でも、ディスパッチします。イベント名が-ing
で終わるイベントは、モデルへの変更が永続化される前にディスパッチされ、-ed
で終わるイベントは、モデルへの変更が永続化された後にディスパッチされます。The retrieved
event will dispatch 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 dispatch. The updating
/ updated
events will dispatch when an existing model is modified and the save
method is called. The saving
/ saved
events will dispatch when a model is created or updated - even if the model's attributes have not been changed. Event names ending with -ing
are dispatched before any changes to the model are persisted, while events ending with -ed
are dispatched after the changes to the model are persisted.
モデルイベントのリッスンを開始するには、Eloquentモデルで$dispatchesEvents
プロパティを定義します。このプロパティは、Eloquentモデルのライフサイクルのさまざまなポイントを独自のイベントクラスにマップします。各モデルイベントクラスはコンストラクターにより、影響を受けるモデルのインスタンスを引数に受け取ります。To start listening to model events, define a $dispatchesEvents
property on your Eloquent model. This property maps various points of the Eloquent model's lifecycle to your own event classes[/docs/{{version}}/events]. Each model event class should expect to receive an instance of the affected model via its constructor:
<?php
namespace App\Models;
use App\Events\UserDeleted;
use App\Events\UserSaved;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
class User extends Authenticatable
{
use Notifiable;
/**
* モデルのイベントマップ
*
* @var array<string, string>
*/
protected $dispatchesEvents = [
'saved' => UserSaved::class,
'deleted' => UserDeleted::class,
];
}
Eloquentイベントを定義してマッピングした後は、そのイベントを処理するためにイベントリスナを使用します。After defining and mapping your Eloquent events, you may use event listeners[/docs/{{version}}/events#defining-listeners] to handle the events.
Warning! Eloquentを介して一括更新または削除クエリを発行する場合、影響を受けるモデルに対して、
saved
、updated
、deleting
、deleted
モデルイベントをディスパッチしません。これは、一括更新または一括削除を実行するときにモデルを実際に取得しないためです。[!WARNING]
When issuing a mass update or delete query via Eloquent, thesaved
,updated
,deleting
, anddeleted
model events will not be dispatched for the affected models. This is because the models are never actually retrieved when performing mass updates or deletes.
クロージャの使用Using Closures
カスタムイベントクラスを使用する代わりに、さまざまなモデルイベントがディスパッチされたときに実行するクロージャを登録できます。通常、これらのクロージャはモデルの「booted」メソッドで登録する必要があります。Instead of using custom event classes, you may register closures that execute when various model events are dispatched. Typically, you should register these closures in the booted
method of your model:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
/**
* モデルの"booted"メソッド
*/
protected static function booted(): void
{
static::created(function (User $user) {
// ...
});
}
}
必要に応じて、モデルイベントを登録するときに、キュー投入可能な匿名イベントリスナを利用できます。これにより、アプリケーションのキューを使用し、バックグラウンドでモデルイベントリスナを実行するようにLaravelに指示できます。If needed, you may utilize queueable anonymous event listeners[/docs/{{version}}/events#queuable-anonymous-event-listeners] when registering model events. This will instruct Laravel to execute the model event listener in the background using your application's queue[/docs/{{version}}/queues]:
use function Illuminate\Events\queueable;
static::created(queueable(function (User $user) {
// ...
}));
オブザーバObservers
オブザーバの定義Defining Observers
特定のモデルで多くのイベントをリッスンしている場合は、オブザーバを使用してすべてのリスナを1つのクラスにグループ化できます。オブザーバクラスは、リッスンする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. Observer classes have method names which reflect the Eloquent events you wish to listen for. Each of these methods receives the affected 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\Models\User;
class UserObserver
{
/**
* ユーザーの"created"イベントの処理
*/
public function created(User $user): void
{
// ...
}
/**
* ユーザーの"updated"イベントの処理
*/
public function updated(User $user): void
{
// ...
}
/**
* ユーザーの"deleted"イベントの処理
*/
public function deleted(User $user): void
{
// ...
}
/**
* ユーザーの"restored"イベントの処理
*/
public function restored(User $user): void
{
// ...
}
/**
* ユーザーの"forceDeleted"イベントの処理
*/
public function forceDeleted(User $user): void
{
// ...
}
}
オブザーバを登録するには、対応するモデルへObservedBy
アトリビュートを指定します。To register an observer, you may place the ObservedBy
attribute on the corresponding model:
use App\Observers\UserObserver;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
#[ObservedBy([UserObserver::class])]
class User extends Authenticatable
{
//
}
あるいは、監視したいモデルに対し、observe
メソッドを呼び出し、手作業でオブザーバを登録することもできます。アプリケーションのAppServiceProvider
クラスのboot
メソッドでオブザーバを登録してください。Or, you may manually register an observer by invoking the observe
method on the model you wish to observe. You may register observers in the boot
method of your application's AppServiceProvider
class:
use App\Models\User;
use App\Observers\UserObserver;
/**
* 全アプリケーションサービスの初期起動処理
*/
public function boot(): void
{
User::observe(UserObserver::class);
}
Note: オブザーバがリッスンできる他のイベントには、
saving
やretrieved
などがあります。こうしたイベントについては、イベントのドキュメントで説明しています。[!NOTE]
There are additional events an observer can listen to, such assaving
andretrieved
. These events are described within the events[#events] documentation.
オブザーバとデータベーストランザクションObservers and Database Transactions
データベーストランザクション内でモデルを作成している場合、データベーストランザクションがコミットされた後にのみイベントハンドラを実行するようにオブザーバへ指示したい場合があるでしょう。これを実現するには、オブザーバでShouldHandleEventsAfterCommit
インターフェイスを実装します。データベーストランザクションが進行中でなければ、イベントハンドラは直ちに実行されます。When models are being created within a database transaction, you may want to instruct an observer to only execute its event handlers after the database transaction is committed. You may accomplish this by implementing the ShouldHandleEventsAfterCommit
interface on your observer. If a database transaction is not in progress, the event handlers will execute immediately:
<?php
namespace App\Observers;
use App\Models\User;
use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
class UserObserver implements ShouldHandleEventsAfterCommit
{
/**
* ユーザーの"created"イベントの処理
*/
public function created(User $user): void
{
// ...
}
}
イベントのミュートMuting Events
モデルにより発生するすべてのイベントを一時的に「ミュート」したい場合が起こりえます。実現するには、withoutEvents
メソッドを使います。withoutEvents
メソッドは、クロージャを唯一の引数として取ります。このクロージャ内で実行するコードはモデルイベントを発行させず、クロージャが返す値はすべてwithoutEvents
メソッドが返します。You may occasionally need to temporarily "mute" all events fired by a model. You may achieve this using the withoutEvents
method. The withoutEvents
method accepts a closure as its only argument. Any code executed within this closure will not dispatch model events, and any value returned by the closure will be returned by the withoutEvents
method:
use App\Models\User;
$user = User::withoutEvents(function () {
User::findOrFail(1)->delete();
return User::find(2);
});
イベントなしの単一モデル保存Saving a Single Model Without Events
イベントをディスパッチせずに、特定のモデルを「保存」したい場合があります。その場合は、saveQuietly
メソッドを使用してください。Sometimes you may wish to "save" a given model without dispatching any events. You may accomplish this using the saveQuietly
method:
$user = User::findOrFail(1);
$user->name = 'Victoria Faith';
$user->saveQuietly();
また、イベントをディスパッチせずに、与えられたモデルを「更新(update)」、「削除(delete)」、「ソフトデリート(soft delete)」、「復元(restore)」、「複製(replicate)」できます。You may also "update", "delete", "soft delete", "restore", and "replicate" a given model without dispatching any events:
$user->deleteQuietly();
$user->forceDeleteQuietly();
$user->restoreQuietly();