Laravel 11.x Eloquent:リレーション

イントロダクションIntroduction

多くの場合、データベーステーブルは相互に関連（リレーション）しています。たとえば、ブログ投稿に多くのコメントが含まれている場合や、注文がそれを行ったユーザーと関連している場合などです。Eloquentはこれらの関係の管理と操作を容易にし、さまざまな一般的なリレーションをサポートします。Database tables are often related to one another. For example, a blog post may have many comments or an order could be related to the user who placed it. Eloquent makes managing and working with these relationships easy, and supports a variety of common relationships:

リレーションの定義Defining Relationships

Eloquentリレーションは、Eloquentモデルクラスのメソッドとして定義します。リレーションは強力なクエリビルダとしても機能するため、リレーションをメソッドとして定義すると、強力なメソッドチェーンとクエリ機能が使用できます。たとえば以下のように、postsリレーションに追加のクエリ制約をチェーンできます。Eloquent relationships are defined as methods on your Eloquent model classes. Since relationships also serve as powerful query builders[/docs/{{version}}/queries], defining relationships as methods provides powerful method chaining and querying capabilities. For example, we may chain additional query constraints on this posts relationship:

$user->posts()->where('active', 1)->get();

ただし、リレーションの使用について深く掘り下げる前に、Eloquentがサポートしている各タイプのリレーションを定義する方法を学びましょう。But, before diving too deep into using relationships, let's learn how to define each type of relationship supported by Eloquent.

１対１One to One

１対１の関係はもっとも基本的なタイプのデータベースリレーションです。たとえば、Userモデルが1つのPhoneモデルに関連付けられている場合があります。この関係を定義するために、Userモデルにphoneメソッドを配置します。phoneメソッドはhasOneメソッドを呼び出し、その結果を返す必要があります。hasOneメソッドは、モデルのIlluminate\Database\Eloquent\Model基本クラスを介してモデルで使用可能です。A one-to-one relationship is a very basic type of database relationship. For example, a User model might be associated with one Phone model. To define this relationship, we will place a phone method on the User model. The phone method should call the hasOne method and return its result. The hasOne method is available to your model via the model's Illuminate\Database\Eloquent\Model base class:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasOne;

class User extends Model
{
    /**
     * ユーザーに関連している電話の取得
     */
    public function phone(): HasOne
    {
        return $this->hasOne(Phone::class);
    }
}

hasOneメソッドに渡される最初の引数は、関連するモデルクラスの名前です。関係を定義すると、Eloquentの動的プロパティを使用して関連レコードを取得できます。動的プロパティを使用すると、モデル上で定義しているプロパティのように、リレーションメソッドへアクセスできます。The first argument passed to the hasOne method is the name of the related model class. Once the relationship is defined, we may retrieve the related record using Eloquent's dynamic properties. Dynamic properties allow you to access relationship methods as if they were properties defined on the model:

$phone = User::find(1)->phone;

Eloquentは、親モデル名に基づきリレーションの外部キーを決定します。この場合、Phoneモデルは自動的にuser_id外部キーを持っているとみなします。この規約をオーバーライドしたい場合は、hasOneメソッドに２番目の引数を渡します。Eloquent determines the foreign key of the relationship based on the parent model name. In this case, the Phone model is automatically assumed to have a user_id foreign key. If you wish to override this convention, you may pass a second argument to the hasOne method:

return $this->hasOne(Phone::class, 'foreign_key');

さらに、Eloquentは、外部キーの値が親の主キーカラムに一致すると想定しています。つまり、Eloquentは、Phoneレコードのuser_idカラムでユーザーのidカラムの値を検索します。リレーションでidまたはモデルの$primaryKeyプロパティ以外の主キー値を使用する場合は、３番目の引数をhasOneメソッドに渡してください。Additionally, Eloquent assumes that the foreign key should have a value matching the primary key column of the parent. In other words, Eloquent will look for the value of the user's id column in the user_id column of the Phone record. If you would like the relationship to use a primary key value other than id or your model's $primaryKey property, you may pass a third argument to the hasOne method:

return $this->hasOne(Phone::class, 'foreign_key', 'local_key');

逆の関係の定義Defining the Inverse of the Relationship

UserモデルからPhoneモデルへアクセスできるようになりました。次に、電話の所有ユーザーへアクセスできるようにするPhoneモデルの関係を定義しましょう。belongsToメソッドを使用してhasOne関係の逆を定義できます。So, we can access the Phone model from our User model. Next, let's define a relationship on the Phone model that will let us access the user that owns the phone. We can define the inverse of a hasOne relationship using the belongsTo method:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Phone extends Model
{
    /**
     * この電話を所有しているユーザーの取得
     */
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

userメソッドを呼び出し時に、EloquentはPhoneモデルのuser_idカラムと一致するidを持つUserモデルを見つけようとします。When invoking the user method, Eloquent will attempt to find a User model that has an id which matches the user_id column on the Phone model.

Eloquentは、リレーションメソッドの名前を調べ、メソッド名の末尾に_idを付けることにより、外部キー名を決定します。したがって、この場合、EloquentはPhoneモデルにuser_idカラムがあると想定します。ただし、Phoneモデルの外部キーがuser_idでない場合は、カスタムキー名をbelongsToメソッドの２番目の引数として渡してください。Eloquent determines the foreign key name by examining the name of the relationship method and suffixing the method name with _id. So, in this case, Eloquent assumes that the Phone model has a user_id column. However, if the foreign key on the Phone model is not user_id, you may pass a custom key name as the second argument to the belongsTo method:

/**
 * この電話を所有しているユーザーの取得
 */
public function user(): BelongsTo
{
    return $this->belongsTo(User::class, 'foreign_key');
}

親モデルが主キーとしてidを使用しない場合、または別のカラムを使用して関連モデルを検索する場合は、belongsToメソッドへ親テーブルのカスタムキーを指定する３番目の引数を渡してください。If the parent model does not use id as its primary key, or you wish to find the associated model using a different column, you may pass a third argument to the belongsTo method specifying the parent table's custom key:

/**
 * この電話を所有しているユーザーの取得
 */
public function user(): BelongsTo
{
    return $this->belongsTo(User::class, 'foreign_key', 'owner_key');
}

１対多One to Many

１対多の関係は、単一のモデルが1つ以上の子モデルの親である関係を定義するために使用されます。たとえば、ブログ投稿はいくつもコメントを持つ場合があります。他のすべてのEloquent関係と同様に、１対多の関係はEloquentモデルでメソッドを定義することにより定義します。A one-to-many relationship is used to define relationships where a single model is the parent to one or more child models. For example, a blog post may have an infinite number of comments. Like all other Eloquent relationships, one-to-many relationships are defined by defining a method on your Eloquent model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Post extends Model
{
    /**
     * ブログポストのコメントを取得
     */
    public function comments(): HasMany
    {
        return $this->hasMany(Comment::class);
    }
}

Eloquentは、Commentモデルの適切な外部キーカラムを自動的に決定することを覚えておきましょう。規約により、Eloquentは親モデルの「スネークケース」名に「_id」という接尾辞を付けます。したがって、この例では、EloquentはCommentモデルの外部キーカラムがpost_idであると想定します。Remember, Eloquent will automatically determine the proper foreign key column for the Comment model. By convention, Eloquent will take the "snake case" name of the parent model and suffix it with _id. So, in this example, Eloquent will assume the foreign key column on the Comment model is post_id.

リレーションメソッドを定義したら、commentsプロパティにアクセスして、関連するコメントのコレクションにアクセスできます。Eloquentは「動的リレーションプロパティ」を提供するため、モデルのプロパティとして定義されているかのようにリレーションメソッドにアクセスできることを思い出してください。Once the relationship method has been defined, we can access the collection[/docs/{{version}}/eloquent-collections] of related comments by accessing the comments property. Remember, since Eloquent provides "dynamic relationship properties", we can access relationship methods as if they were defined as properties on the model:

use App\Models\Post;

$comments = Post::find(1)->comments;

foreach ($comments as $comment) {
    // ...
}

すべての関係はクエリビルダとしても機能するため、commentsメソッドを呼び出し、クエリに条件をチェーンし続けて、リレーションのクエリへさらに制約を追加できます。Since all relationships also serve as query builders, you may add further constraints to the relationship query by calling the comments method and continuing to chain conditions onto the query:

$comment = Post::find(1)->comments()
                    ->where('title', 'foo')
                    ->first();

hasOneメソッドと同様に、hasManyメソッドに追加の引数を渡すことにより、外部キーとローカルキーをオーバーライドすることもできます。Like the hasOne method, you may also override the foreign and local keys by passing additional arguments to the hasMany method:

return $this->hasMany(Comment::class, 'foreign_key');

return $this->hasMany(Comment::class, 'foreign_key', 'local_key');

１対多（逆）／所属One to Many (Inverse) / Belongs To

投稿のすべてのコメントへアクセスできるようになったので、今度はコメントからその親投稿へアクセスできるようにする関係を定義しましょう。hasMany関係の逆を定義するには、belongsToメソッドを呼び出す子モデルで関係メソッドを定義します。Now that we can access all of a post's comments, let's define a relationship to allow a comment to access its parent post. To define the inverse of a hasMany relationship, define a relationship method on the child model which calls the belongsTo method:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Comment extends Model
{
    /**
     * コメントを所有している投稿を取得
     */
    public function post(): BelongsTo
    {
        return $this->belongsTo(Post::class);
    }
}

リレーションを定義したら、postの「動的リレーションプロパティ」にアクセスして、コメントの親投稿を取得できます。Once the relationship has been defined, we can retrieve a comment's parent post by accessing the post "dynamic relationship property":

use App\Models\Comment;

$comment = Comment::find(1);

return $comment->post->title;

上記の例でEloquentは、Commentモデルのpost_idカラムと一致するidを持つPostモデルを見つけようとします。In the example above, Eloquent will attempt to find a Post model that has an id which matches the post_id column on the Comment model.

Eloquentはリレーションメソッドの名前を調べ、メソッド名の末尾に"_"を付けてから、親モデルの主キーカラムの名前を付けることにより、デフォルトの外部キー名を決定します。したがって、この例では、EloquentはcommentsテーブルのPostモデルへの外部キーがpost_idであると想定します。Eloquent determines the default foreign key name by examining the name of the relationship method and suffixing the method name with a _ followed by the name of the parent model's primary key column. So, in this example, Eloquent will assume the Post model's foreign key on the comments table is post_id.

ただし、リレーションの外部キーがこの規約に従わない場合は、カスタム外部キー名をbelongsToメソッドの２番目の引数へ指定できます。However, if the foreign key for your relationship does not follow these conventions, you may pass a custom foreign key name as the second argument to the belongsTo method:

/**
 * コメントを所有している投稿を取得
 */
public function post(): BelongsTo
{
    return $this->belongsTo(Post::class, 'foreign_key');
}

親モデルが主キーとしてidを使用していない場合、または別のカラムを使用して関連モデルを検索する場合は、belongsToメソッドへ親テーブルのカスタムキーを指定する３番目の引数を渡せます。If your parent model does not use id as its primary key, or you wish to find the associated model using a different column, you may pass a third argument to the belongsTo method specifying your parent table's custom key:

/**
 * コメントを所有している投稿を取得
 */
public function post(): BelongsTo
{
    return $this->belongsTo(Post::class, 'foreign_key', 'owner_key');
}

デフォルトモデルDefault Models

belongsTo、hasOne、hasOneThrough、morphOneリレーションを使用する場合、指定する関係がnullの場合に返すデフォルトモデルを定義できます。このパターンは、Nullオブジェクトパターンと呼ばれることが多く、コード内の条件付きチェックを省略するのに役立ちます。以下の例では、Postモデルにユーザーがアタッチされていない場合、userリレーションは空のApp\Models\Userモデルを返します。The belongsTo, hasOne, hasOneThrough, and morphOne relationships allow you to define a default model that will be returned if the given relationship is null. This pattern is often referred to as the Null Object pattern[https://en.wikipedia.org/wiki/Null_Object_pattern] and can help remove conditional checks in your code. In the following example, the user relation will return an empty App\Models\User model if no user is attached to the Post model:

/**
 * 投稿の作成者を取得
 */
public function user(): BelongsTo
{
    return $this->belongsTo(User::class)->withDefault();
}

デフォルトモデルに属性を設定するには、配列またはクロージャをwithDefaultメソッドに渡します。To populate the default model with attributes, you may pass an array or closure to the withDefault method:

/**
 * 投稿の作成者を取得
 */
public function user(): BelongsTo
{
    return $this->belongsTo(User::class)->withDefault([
        'name' => 'Guest Author',
    ]);
}

/**
 * 投稿の作成者を取得
 */
public function user(): BelongsTo
{
    return $this->belongsTo(User::class)->withDefault(function (User $user, Post $post) {
        $user->name = 'Guest Author';
    });
}

Belongs toリレーションのクエリQuerying Belongs To Relationships

"belongs to"リレーションの子モデルをクエリする場合は、対応するEloquentモデルを取得するwhere句を手作業で構築してください。When querying for the children of a "belongs to" relationship, you may manually build the where clause to retrieve the corresponding Eloquent models:

use App\Models\Post;

$posts = Post::where('user_id', $user->id)->get();

しかし、whereBelongsToメソッドを使う方が便利でしょう。このメソッドは、与えられたモデルに対して適切なリレーションと外部キーを自動的に決定します。However, you may find it more convenient to use the whereBelongsTo method, which will automatically determine the proper relationship and foreign key for the given model:

$posts = Post::whereBelongsTo($user)->get();

また、whereBelongsToメソッドへ、コレクションインスタンスも指定可能です。その場合、Laravelはコレクション内から、親モデルに所属する全モデルを取得します。You may also provide a collection[/docs/{{version}}/eloquent-collections] instance to the whereBelongsTo method. When doing so, Laravel will retrieve models that belong to any of the parent models within the collection:

$users = User::where('vip', true)->get();

$posts = Post::whereBelongsTo($users)->get();

デフォルトでLaravelはモデルのクラス名に基づいて、与えられたモデルに関連するリレーションを決定しますが、リレーション名をwhereBelongsToメソッドの第２引数に渡すことで、手作業で指定できます。By default, Laravel will determine the relationship associated with the given model based on the class name of the model; however, you may specify the relationship name manually by providing it as the second argument to the whereBelongsTo method:

$posts = Post::whereBelongsTo($user, 'author')->get();

Has One of ManyHas One of Many

あるモデルが多くの関連モデルを持つことがありますが、そのリレーションにおける「最新」または「最も古い」関連モデルを簡単に取得したい場合があります。たとえば、Userモデルは多くのOrderモデルと関連しており、ユーザーが発注した最新の注文を操作する便利な方法を定義したいとします。これの実現には、hasOneのリレーションタイプとofManyメソッドを組み合わせて使います。Sometimes a model may have many related models, yet you want to easily retrieve the "latest" or "oldest" related model of the relationship. For example, a User model may be related to many Order models, but you want to define a convenient way to interact with the most recent order the user has placed. You may accomplish this using the hasOne relationship type combined with the ofMany methods:

/**
 * ユーザーの最新注文の取得
 */
public function latestOrder(): HasOne
{
    return $this->hasOne(Order::class)->latestOfMany();
}

同様に、あるリレーションの「最も古い」、つまり最初の関連モデルを取得するメソッドを定義することもできます。Likewise, you may define a method to retrieve the "oldest", or first, related model of a relationship:

/**
 * ユーザーの最も古い注文を取得
 */
public function oldestOrder(): HasOne
{
    return $this->hasOne(Order::class)->oldestOfMany();
}

latestOfManyとoldestOfManyメソッドはデフォルトで、ソート可能なモデルの主キーに基づいて、最新または最古の関連モデルを取得します。しかし、時には、別のソート基準を使って、より大きなリレーションから単一モデルを取得したい場合も起きるでしょう。By default, the latestOfMany and oldestOfMany methods will retrieve the latest or oldest related model based on the model's primary key, which must be sortable. However, sometimes you may wish to retrieve a single model from a larger relationship using a different sorting criteria.

例えば、ofManyメソッドを使って、ユーザーの最も高い注文を取得することができます。ofManyメソッドは、ソート可能なカラムを第一引数として受け取り、関連するモデルを検索する際にどの集約関数（minまたはmax）を適用するかを指定します。For example, using the ofMany method, you may retrieve the user's most expensive order. The ofMany method accepts the sortable column as its first argument and which aggregate function (min or max) to apply when querying for the related model:

/**
 * ユーザーの一番高い注文の取得
 */
public function largestOrder(): HasOne
{
    return $this->hasOne(Order::class)->ofMany('price', 'max');
}

warning Warning! PostgreSQLはUUID列に対するMAX関数の実行をサポートしていないため、今のところPostgreSQLのUUIDカラムと組み合わせて１対多の関係を使用できません。[!WARNING]
Because PostgreSQL does not support executing the MAX function against UUID columns, it is not currently possible to use one-of-many relationships in combination with PostgreSQL UUID columns.

"Many"リレーションをHas Oneリレーションへ変換するConverting "Many" Relationships to Has One Relationships

latestOfMany、oldestOfMany、ofManyメソッドを使用して単一のモデルを取得するとき、多くの場合、同じモデルに対し予め"has many"リレーションが定義済みです。便利なように、Laravelはリレーションでoneメソッドを呼び出すことにより、こうしたリレーションを"has one"リレーションへ簡単に変換できます。Often, when retrieving a single model using the latestOfMany, oldestOfMany, or ofMany methods, you already have a "has many" relationship defined for the same model. For convenience, Laravel allows you to easily convert this relationship into a "has one" relationship by invoking the one method on the relationship:

/**
 * ユーザーの注文の取得
 */
public function orders(): HasMany
{
    return $this->hasMany(Order::class);
}

/**
 * ユーザーの一番高い注文の取得
 */
public function largestOrder(): HasOne
{
    return $this->orders()->one()->ofMany('price', 'max');
}

上級Has One Of ManyリレーションAdvanced Has One of Many Relationships

より高度な"has one of many"リレーションを構築することも可能です。例えば、Productモデルは、新しい価格が公開された後でもシステム内で保持している、多くの関連Priceモデルを持つことができます。さらに、製品の新しい価格データは、published_atカラムにより、将来の日付で有効にするように事前に予約できることにしましょう。It is possible to construct more advanced "has one of many" relationships. For example, a Product model may have many associated Price models that are retained in the system even after new pricing is published. In addition, new pricing data for the product may be able to be published in advance to take effect at a future date via a published_at column.

要約すると、公開日が未来ではない最新の価格を取得する必要があるということです。さらに、２つの価格の公開日が同じであれば、より大きいIDを持つ価格を優先します。これを実現するには、最新の価格を決定するソート可能なカラムを含む配列を ofMany メソッドに渡す必要があります。さらに、ofManyメソッドの第２引数には、クロージャが渡されます。このクロージャは、リレーションクエリに追加の発行日制約を追加する役割を果たします。So, in summary, we need to retrieve the latest published pricing where the published date is not in the future. In addition, if two prices have the same published date, we will prefer the price with the greatest ID. To accomplish this, we must pass an array to the ofMany method that contains the sortable columns which determine the latest price. In addition, a closure will be provided as the second argument to the ofMany method. This closure will be responsible for adding additional publish date constraints to the relationship query:

/**
 * 製品の現在価格を取得
 */
public function currentPricing(): HasOne
{
    return $this->hasOne(Price::class)->ofMany([
        'published_at' => 'max',
        'id' => 'max',
    ], function (Builder $query) {
        $query->where('published_at', '<', now());
    });
}

Has One ThroughHas One Through

"has-one-through"リレーションは、別のモデルとの１対１の関係を定義します。ただし、この関係は、３番目のモデルを仲介（through）に使うことで、宣言するモデルと別のモデルの１インスタンスとマッチさせることを意味します。The "has-one-through" relationship defines a one-to-one relationship with another model. However, this relationship indicates that the declaring model can be matched with one instance of another model by proceeding through a third model.

たとえば、自動車修理工場のアプリケーションでは、各「整備士（Mechanic）」モデルを１つの「自動車（Car）」モデルに関連付け、各「自動車」モデルを１つの「所有者（Owner）」モデルに関連付けることができます。整備士と所有者はデータベース内で直接の関係はありませんが、整備士は「車」モデルを介して所有者にアクセスできます。この関係を定義するために必要なテーブルを見てみましょう。For example, in a vehicle repair shop application, each Mechanic model may be associated with one Car model, and each Car model may be associated with one Owner model. While the mechanic and the owner have no direct relationship within the database, the mechanic can access the owner through the Car model. Let's look at the tables necessary to define this relationship:

mechanics
    id - integer
    name - string

cars
    id - integer
    model - string
    mechanic_id - integer

owners
    id - integer
    name - string
    car_id - integer

リレーションのテーブル構造を調べたので、Mechanicモデルで関係を定義しましょう。Now that we have examined the table structure for the relationship, let's define the relationship on the Mechanic model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasOneThrough;

class Mechanic extends Model
{
    /**
     * 車の所有者を取得
     */
    public function carOwner(): HasOneThrough
    {
        return $this->hasOneThrough(Owner::class, Car::class);
    }
}

hasOneThroughメソッドに渡す、最初の引数はアクセスする最終モデルの名前であり、２番目の引数は中間モデルの名前です。The first argument passed to the hasOneThrough method is the name of the final model we wish to access, while the second argument is the name of the intermediate model.

もしくは、関連するリレーションがすべてのモデルで既に定義済みの場合、それらのリレーション名を指定し、throughメソッドを呼び出すことで、"has-one-through"リレーションをスムーズに定義できます。例えば、Mechanicモデルがcarsリレーションを持ち、Carモデルがownerリレーションを持つ場合、メカニックとオーナーを結ぶ"has-one-through"リレーションを次のように定義可能です。Or, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-one-through" relationship by invoking the through method and supplying the names of those relationships. For example, if the Mechanic model has a cars relationship and the Car model has an owner relationship, you may define a "has-one-through" relationship connecting the mechanic and the owner like so:

// 文字列ベース記法
return $this->through('cars')->has('owner');

// 動的記法
return $this->throughCars()->hasOwner();

キーの規約Key Conventions

リレーションのクエリ実行時は、一般的にEloquent外部キー規約を使用します。リレーションのキーをカスタマイズする場合は、それらを３番目と４番目の引数としてhasOneThroughメソッドに渡してください。３番目の引数は、中間モデルの外部キーの名前です。４番目の引数は、最終モデルの外部キーの名前です。５番目の引数はローカルキーであり、６番目の引数は中間モデルのローカルキーです。Typical Eloquent foreign key conventions will be used when performing the relationship's queries. If you would like to customize the keys of the relationship, you may pass them as the third and fourth arguments to the hasOneThrough method. The third argument is the name of the foreign key on the intermediate model. The fourth argument is the name of the foreign key on the final model. The fifth argument is the local key, while the sixth argument is the local key of the intermediate model:

class Mechanic extends Model
{
    /**
     * 車の所有者を取得
     */
    public function carOwner(): HasOneThrough
    {
        return $this->hasOneThrough(
            Owner::class,
            Car::class,
            'mechanic_id', // carsテーブルの外部キー
            'car_id', // ownersテーブルの外部キー
            'id', // mechanicsテーブルのローカルキー
            'id' // carsテーブルのローカルキー
        );
    }
}

あるいは、先に説明したように、関わるすべてのモデルで関連するリレーションが既に定義済みの場合、それらのリレーション名を指定し、throughメソッドを呼び出すことで、"has-one-through"リレーションを流れるように定義することもできます。この方法は、既存のリレーションで定義したキー関係定義を再利用できるという利点があります。Or, as discussed earlier, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-one-through" relationship by invoking the through method and supplying the names of those relationships. This approach offers the advantage of reusing the key conventions already defined on the existing relationships:

// 文字列ベース記法
return $this->through('cars')->has('owner');

// 動的記法
return $this->throughCars()->hasOwner();

Has Many ThroughHas Many Through

"has-many-through"関係は、中間関係を介して離れた関係へアクセスするための便利な方法を提供します。たとえば、Laravel Vaporのようなデプロイメントプラットフォームを構築していると仮定しましょう。Projectモデルは、中間の環境（Environment）モデルを介して多くのDeploymentモデルにアクセスする可能性があります。この例では、特定のプロジェクトの全デプロイメントを簡単に収集できます。この関係を定義するために必要なテーブルを見てみましょう。The "has-many-through" relationship provides a convenient way to access distant relations via an intermediate relation. For example, let's assume we are building a deployment platform like Laravel Vapor[https://vapor.laravel.com]. A Project model might access many Deployment models through an intermediate Environment model. Using this example, you could easily gather all deployments for a given project. Let's look at the tables required to define this relationship:

projects
    id - integer
    name - string

environments
    id - integer
    project_id - integer
    name - string

deployments
    id - integer
    environment_id - integer
    commit_hash - string

リレーションのテーブル構造を調べたので、Projectモデルでリレーションを定義しましょう。Now that we have examined the table structure for the relationship, let's define the relationship on the Project model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasManyThrough;

class Project extends Model
{
    /**
     * プロジェクトのすべてのデプロイメントを取得
     */
    public function deployments(): HasManyThrough
    {
        return $this->hasManyThrough(Deployment::class, Environment::class);
    }
}

hasManyThroughメソッドへ渡たす、最初の引数はアクセスする最終モデルの名前であり、２番目の引数は中間モデルの名前です。The first argument passed to the hasManyThrough method is the name of the final model we wish to access, while the second argument is the name of the intermediate model.

また、既にすべてのモデルで関連リレーションが定義済みの場合は、それらのリレーション名を指定し、throughメソッドを呼び出して、"has-many-through"リレーションシップをスムーズに定義できます。例えば、Projectモデルがenvironmentsリレーションを持ち、Environmentモデルがdeploymentsリレーションを持つ場合、プロジェクトとデプロイメントを結ぶ"has-many-through"リーションを以下のように定義できます。Or, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-many-through" relationship by invoking the through method and supplying the names of those relationships. For example, if the Project model has a environments relationship and the Environment model has a deployments relationship, you may define a "has-many-through" relationship connecting the project and the deployments like so:

// 文字列ベース記法
return $this->through('environments')->has('deployments');

// 動的記法
return $this->throughEnvironments()->hasDeployments();

Deploymentモデルのテーブルはproject_idカラムを含んでいませんが、hasManyThroughリレーションは、$project->deploymentsを介してプロジェクトのデプロイメントへのアクセスを提供します。これらのモデルを取得するために、Eloquentは中間のEnvironmentモデルのテーブルのproject_idカラムを検査します。関連した環境IDを見つけ、それらを使用してDeploymentモデルのテーブルをクエリします。Though the Deployment model's table does not contain a project_id column, the hasManyThrough relation provides access to a project's deployments via $project->deployments. To retrieve these models, Eloquent inspects the project_id column on the intermediate Environment model's table. After finding the relevant environment IDs, they are used to query the Deployment model's table.

キーの規約Key Conventions

リレーションのクエリを実行するときは、Eloquent外部キー規約を一般的に使用します。リレーションのキーをカスタマイズする場合は、それらを３番目と４番目の引数としてhasManyThroughメソッドに渡たしてください。３番目の引数は、中間モデルの外部キーの名前です。４番目の引数は、最終モデルの外部キーの名前です。５番目の引数はローカルキーであり、６番目の引数は中間モデルのローカルキーです。Typical Eloquent foreign key conventions will be used when performing the relationship's queries. If you would like to customize the keys of the relationship, you may pass them as the third and fourth arguments to the hasManyThrough method. The third argument is the name of the foreign key on the intermediate model. The fourth argument is the name of the foreign key on the final model. The fifth argument is the local key, while the sixth argument is the local key of the intermediate model:

class Project extends Model
{
    public function deployments(): HasManyThrough
    {
        return $this->hasManyThrough(
            Deployment::class,
            Environment::class,
            'project_id', // environmentsテーブルの外部キー
            'environment_id', // deploymentsテーブルの外部キー
            'id', // projectsテーブルのローカルキー
            'id' // environmentsテーブルのローカルキー
        );
    }
}

あるいは、先に説明したように、関連リレーションがリレーションに関わるすべてのモデルで、定義済みの場合、それらのリレーション名を指定し、throughメソッドを呼び出すことで、"has-many-through"リレーションをスムーズに定義することも可能です。この方法は、既存のリレーションに定義されているキー関係定義を再利用できるという利点があります。Or, as discussed earlier, if the relevant relationships have already been defined on all of the models involved in the relationship, you may fluently define a "has-many-through" relationship by invoking the through method and supplying the names of those relationships. This approach offers the advantage of reusing the key conventions already defined on the existing relationships:

// 文字列ベース記法
return $this->through('environments')->has('deployments');

// 動的記法
return $this->throughEnvironments()->hasDeployments();

多対多リレーションMany to Many Relationships

多対多の関係は、hasOneおよびhasManyの関係よりも少し複雑です。多対多の関係の一例は、多くの役割を持つユーザーであり、役割はアプリケーション内の他のユーザーと共有している場合です。たとえば、あるユーザーに「作成者（Author）」と「編集者（Editor）」の役割を割り当てることができます。ただし、これらの役割は他のユーザーにも割り当てる場合があります。したがって、あるユーザーには多くの役割があり、ある役割には多くのユーザーがいます。Many-to-many relations are slightly more complicated than hasOne and hasMany relationships. An example of a many-to-many relationship is a user that has many roles and those roles are also shared by other users in the application. For example, a user may be assigned the role of "Author" and "Editor"; however, those roles may also be assigned to other users as well. So, a user has many roles and a role has many users.

テーブル構造Table Structure

この関係を定義するには、users、roles、およびrole_userの３つのデータベーステーブルが必要です。role_userテーブルは、関連モデル名のアルファベット順を由来としており、user_idカラムとrole_idカラムを含みます。このテーブルは、ユーザーと役割をリンクする中間テーブルとして使用します。To define this relationship, three database tables are needed: users, roles, and role_user. The role_user table is derived from the alphabetical order of the related model names and contains user_id and role_id columns. This table is used as an intermediate table linking the users and roles.

役割は多くのユーザーに属することができるため、単にuser_idカラムをrolesテーブルに配置することはできません。そうすることは、役割が１人のユーザーにのみ属することができることを意味します。複数のユーザーに割り当てられている役割（role）をサポートするには、role_userテーブルが必要です。リレーションのテーブル構造は次のように要約できます。Remember, since a role can belong to many users, we cannot simply place a user_id column on the roles table. This would mean that a role could only belong to a single user. In order to provide support for roles being assigned to multiple users, the role_user table is needed. We can summarize the relationship's table structure like so:

users
    id - integer
    name - string

roles
    id - integer
    name - string

role_user
    user_id - integer
    role_id - integer

モデル構造Model Structure

多対多の関係は、belongsToManyメソッドの結果を返すメソッドを作成して定義します。belongsToManyメソッドは、アプリケーションのすべてのEloquentモデルで使用しているIlluminate\Database\Eloquent\Model基本クラスが提供しています。例として、Userモデル上のrolesメソッドを定義してみましょう。このメソッドへ渡す最初の引数は、関連するモデルクラスの名前です。Many-to-many relationships are defined by writing a method that returns the result of the belongsToMany method. The belongsToMany method is provided by the Illuminate\Database\Eloquent\Model base class that is used by all of your application's Eloquent models. For example, let's define a roles method on our User model. The first argument passed to this method is the name of the related model class:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

class User extends Model
{
    /**
     * このユーザーに属する役割
     */
    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(Role::class);
    }
}

リレーションを定義したら、roles動的リレーションプロパティを使用してユーザーの役割へアクセスできます。Once the relationship is defined, you may access the user's roles using the roles dynamic relationship property:

use App\Models\User;

$user = User::find(1);

foreach ($user->roles as $role) {
    // ...
}

すべてのリレーションはクエリビルダとしても機能するため、rolesメソッドを呼び出し、クエリに条件をチェーンによりつなげることで、リレーションのクエリへさらに制約を追加できます。Since all relationships also serve as query builders, you may add further constraints to the relationship query by calling the roles method and continuing to chain conditions onto the query:

$roles = User::find(1)->roles()->orderBy('name')->get();

リレーションの中間テーブルのテーブル名を決定するために、Eloquentは２つの関連するモデル名をアルファベット順に結合します。ただし、この規約は自由に上書きできます。その場合、２番目の引数をbelongsToManyメソッドに渡します。To determine the table name of the relationship's intermediate table, Eloquent will join the two related model names in alphabetical order. However, you are free to override this convention. You may do so by passing a second argument to the belongsToMany method:

return $this->belongsToMany(Role::class, 'role_user');

中間テーブルの名前をカスタマイズすることに加えて、belongsToManyメソッドへ追加の引数を渡し、テーブルのキーのカラム名をカスタマイズすることもできます。３番目の引数は、関係を定義しているモデルの外部キー名であり、４番目の引数は、関連付けるモデルの外部キー名です。In addition to customizing the name of the intermediate table, you may also customize the column names of the keys on the table by passing additional arguments to the belongsToMany method. The third argument is the foreign key name of the model on which you are defining the relationship, while the fourth argument is the foreign key name of the model that you are joining to:

return $this->belongsToMany(Role::class, 'role_user', 'user_id', 'role_id');

逆の関係の定義Defining the Inverse of the Relationship

多対多の関係の「逆」を定義するには、関連モデルでメソッドを定義する必要があります。このメソッドは、belongsToManyメソッドの結果も返します。ユーザー／ロールの例を完成させるために、Roleモデルでusersメソッドを定義しましょう。To define the "inverse" of a many-to-many relationship, you should define a method on the related model which also returns the result of the belongsToMany method. To complete our user / role example, let's define the users method on the Role model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

class Role extends Model
{
    /**
     * この役割に属するユーザー
     */
    public function users(): BelongsToMany
    {
        return $this->belongsToMany(User::class);
    }
}

ご覧のとおり。関係は、App\Models\Userモデルを参照することを除いて、対応するUserモデルとまったく同じように定義されています。belongsToManyメソッドを再利用しているため、多対多の関係の「逆」を定義するときにも、通常のテーブルとキーのカスタマイズオプションをすべて使用できます。As you can see, the relationship is defined exactly the same as its User model counterpart with the exception of referencing the App\Models\User model. Since we're reusing the belongsToMany method, all of the usual table and key customization options are available when defining the "inverse" of many-to-many relationships.

中間テーブルカラムの取得Retrieving Intermediate Table Columns

すでに学んだように、多対多の関係を扱うには、中間テーブルの存在が必要です。Eloquentは、このテーブルを操作するのに役立つ手段をいくつか提供しています。たとえば、Userモデルに関連するRoleモデルがたくさんあるとしましょう。この関係にアクセスした後、モデルのpivot属性を使用して中間テーブルにアクセスできます。As you have already learned, working with many-to-many relations requires the presence of an intermediate table. Eloquent provides some very helpful ways of interacting with this table. For example, let's assume our User model has many Role models that it is related to. After accessing this relationship, we may access the intermediate table using the pivot attribute on the models:

use App\Models\User;

$user = User::find(1);

foreach ($user->roles as $role) {
    echo $role->pivot->created_at;
}

取得する各Roleモデルには自動的にpivot属性が割り当てられることに注意してください。この属性には、中間テーブルを表すモデルが含まれています。Notice that each Role model we retrieve is automatically assigned a pivot attribute. This attribute contains a model representing the intermediate table.

デフォルトでは、モデルキーのみがpivotモデルに存在します。中間テーブルに追加の属性を含めている場合は、関係を定義するときにそうした属性を指定する必要があります。By default, only the model keys will be present on the pivot model. If your intermediate table contains extra attributes, you must specify them when defining the relationship:

return $this->belongsToMany(Role::class)->withPivot('active', 'created_by');

中間テーブルへEloquentが自動的に維持するcreated_atおよびupdated_atタイムスタンプを持たせたい場合は、関係を定義するときにwithTimestampsメソッドを呼び出します。If you would like your intermediate table to have created_at and updated_at timestamps that are automatically maintained by Eloquent, call the withTimestamps method when defining the relationship:

return $this->belongsToMany(Role::class)->withTimestamps();

warning Warning! Eloquentが自動で維持するタイムスタンプを利用する中間テーブルには、created_atとupdated_at両方のタイムスタンプカラムが必要です。[!WARNING]
Intermediate tables that utilize Eloquent's automatically maintained timestamps are required to have both created_at and updated_at timestamp columns.

pivot属性名のカスタマイズCustomizing the pivot Attribute Name

前述のように、中間テーブルの属性はモデルのpivot属性を介してアクセスできます。この属性の名前は、アプリケーション内での目的をより適切に反映するため、自由にカスタマイズできます。As noted previously, attributes from the intermediate table may be accessed on models via the pivot attribute. However, you are free to customize the name of this attribute to better reflect its purpose within your application.

たとえば、アプリケーションにポッドキャストを購読する可能性のあるユーザーが含まれている場合、ユーザーとポッドキャストの間には多対多の関係があるでしょう。この場合、中間テーブル属性の名前をpivotではなくsubscriptionに変更することを推奨します。リレーションを定義するときにasメソッドを使用して指定できます。For example, if your application contains users that may subscribe to podcasts, you likely have a many-to-many relationship between users and podcasts. If this is the case, you may wish to rename your intermediate table attribute to subscription instead of pivot. This can be done using the as method when defining the relationship:

return $this->belongsToMany(Podcast::class)
                ->as('subscription')
                ->withTimestamps();

カスタム中間テーブル属性を指定し終えると、カスタマイズした名前を使用して中間テーブルのデータへアクセスできます。Once the custom intermediate table attribute has been specified, you may access the intermediate table data using the customized name:

$users = User::with('podcasts')->get();

foreach ($users->flatMap->podcasts as $podcast) {
    echo $podcast->subscription->created_at;
}

中間テーブルのカラムを使った関係のフィルタリングFiltering Queries via Intermediate Table Columns

リレーションを定義するときに、wherePivot、wherePivotIn、wherePivotNotIn、wherePivotBetween、wherePivotNotBetween、wherePivotNull、wherePivotNotNullメソッドを使用し、belongsToMany関係クエリによって返される結果をフィルタリングすることもできます。You can also filter the results returned by belongsToMany relationship queries using the wherePivot, wherePivotIn, wherePivotNotIn, wherePivotBetween, wherePivotNotBetween, wherePivotNull, and wherePivotNotNull methods when defining the relationship:

return $this->belongsToMany(Role::class)
                ->wherePivot('approved', 1);

return $this->belongsToMany(Role::class)
                ->wherePivotIn('priority', [1, 2]);

return $this->belongsToMany(Role::class)
                ->wherePivotNotIn('priority', [1, 2]);

return $this->belongsToMany(Podcast::class)
                ->as('subscriptions')
                ->wherePivotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);

return $this->belongsToMany(Podcast::class)
                ->as('subscriptions')
                ->wherePivotNotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);

return $this->belongsToMany(Podcast::class)
                ->as('subscriptions')
                ->wherePivotNull('expired_at');

return $this->belongsToMany(Podcast::class)
                ->as('subscriptions')
                ->wherePivotNotNull('expired_at');

中間テーブルカラムによるクエリの並び替えOrdering Queries via Intermediate Table Columns

belongsToMany リレーションクエリが返す結果は、orderByPivotメソッドを使用して並び替えできます。以下の例では、そのユーザーの最新バッジをすべて取得します。You can order the results returned by belongsToMany relationship queries using the orderByPivot method. In the following example, we will retrieve all of the latest badges for the user:

return $this->belongsToMany(Badge::class)
                ->where('rank', 'gold')
                ->orderByPivot('created_at', 'desc');

カスタム中間テーブルモデルの定義Defining Custom Intermediate Table Models

多対多の関係の中間（ピボット）テーブルを表すカスタムモデルを定義する場合は、関係定義時にusingメソッドを呼び出してください。カスタムピボットモデルを使用すると、ピボットモデルにメソッドやキャストのような追加動作を定義できます。If you would like to define a custom model to represent the intermediate table of your many-to-many relationship, you may call the using method when defining the relationship. Custom pivot models give you the opportunity to define additional behavior on the pivot model, such as methods and casts.

カスタムの多対多ピボットモデルはIlluminate\Database\Eloquent\Relationships\Pivotクラス、カスタムのポリモーフィック多対多ピボットモデルはIlluminate\Database\Eloquent\Relationships\MorphPivotクラスを拡張する必要があります。たとえば、カスタムのRoleUserピボットモデルを使用するRoleモデルを定義してみましょう。Custom many-to-many pivot models should extend the Illuminate\Database\Eloquent\Relations\Pivot class while custom polymorphic many-to-many pivot models should extend the Illuminate\Database\Eloquent\Relations\MorphPivot class. For example, we may define a Role model which uses a custom RoleUser pivot model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;

class Role extends Model
{
    /**
     * この役割に属するユーザー
     */
    public function users(): BelongsToMany
    {
        return $this->belongsToMany(User::class)->using(RoleUser::class);
    }
}

RoleUserモデルを定義するときは、Illuminate\Database\Eloquent\Relationships\Pivotクラスを拡張する必要があります。When defining the RoleUser model, you should extend the Illuminate\Database\Eloquent\Relations\Pivot class:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\Pivot;

class RoleUser extends Pivot
{
    // ...
}

warning Warning! ピボットモデルはSoftDeletesトレイトを使用できません。ピボットレコードをソフトデリートする必要がある場合は、ピボットモデルを実際のEloquentモデルに変換することを検討してください。[!WARNING]
Pivot models may not use the SoftDeletes trait. If you need to soft delete pivot records consider converting your pivot model to an actual Eloquent model.

カスタムピボットモデルと増分IDCustom Pivot Models and Incrementing IDs

カスタムピボットモデルを使用する多対多の関係を定義し、そのピボットモデルに自動増分の主キーがある場合は、カスタムピボットモデルクラスでincrementingプロパティを確実にtrueに設定してください。If you have defined a many-to-many relationship that uses a custom pivot model, and that pivot model has an auto-incrementing primary key, you should ensure your custom pivot model class defines an incrementing property that is set to true.

/**
 * IDの自動増分を指定する
 *
 * @var bool
 */
public $incrementing = true;

ポリモーフィックリレーションPolymorphic Relationships

ポリモーフィックリレーションにより、子モデルは単一の関連を使用して複数タイプのモデルに属せます。たとえば、ユーザーがブログの投稿やビデオを共有できるようにするアプリケーションを構築しているとします。このようなアプリケーションで、CommentモデルはPostモデルとVideoモデルの両方に属する可能性があります。A polymorphic relationship allows the child model to belong to more than one type of model using a single association. For example, imagine you are building an application that allows users to share blog posts and videos. In such an application, a Comment model might belong to both the Post and Video models.

１対１（ポリモーフィック）One to One (Polymorphic)

テーブル構造Table Structure

１対１のポリモーフィックリレーションは、一般的な１対１の関係に似ています。ただし、子モデルは単一の関連付けを使用して複数タイプのモデルへ所属できます。たとえば、ブログのPostとUserは、Imageモデルとポリモーフィックな関係を共有することがあります。１対１のポリモーフィックな関係を使用すると、投稿やユーザーに関連するひとつの画像の単一のテーブルを作成できます。まず、テーブルの構造を調べてみましょう。A one-to-one polymorphic relation is similar to a typical one-to-one relation; however, the child model can belong to more than one type of model using a single association. For example, a blog Post and a User may share a polymorphic relation to an Image model. Using a one-to-one polymorphic relation allows you to have a single table of unique images that may be associated with posts and users. First, let's examine the table structure:

posts
    id - integer
    name - string

users
    id - integer
    name - string

images
    id - integer
    url - string
    imageable_id - integer
    imageable_type - string

imagesテーブルのimageable_idカラムとimageable_typeカラムに注意してください。imageable_idカラムには投稿またはユーザーのID値が含まれ、imageable_typeカラムには親モデルのクラス名が含まれます。imageable_typeカラムは、imageableリレーションへのアクセス時に返す親モデルの「タイプ」を決めるため、Eloquentが使用します。この場合、カラムにはApp\Models\PostかApp\Models\Userのどちらかが入ります。Note the imageable_id and imageable_type columns on the images table. The imageable_id column will contain the ID value of the post or user, while the imageable_type column will contain the class name of the parent model. The imageable_type column is used by Eloquent to determine which "type" of parent model to return when accessing the imageable relation. In this case, the column would contain either App\Models\Post or App\Models\User.

モデル構造Model Structure

次に、この関係を構築するために必要なモデルの定義を見てみましょう。Next, let's examine the model definitions needed to build this relationship:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphTo;

class Image extends Model
{
    /**
     * 親のimageableなモデル（ユーザー／投稿）の取得
     */
    public function imageable(): MorphTo
    {
        return $this->morphTo();
    }
}

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphOne;

class Post extends Model
{
    /**
     * 投稿の画像を取得
     */
    public function image(): MorphOne
    {
        return $this->morphOne(Image::class, 'imageable');
    }
}

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphOne;

class User extends Model
{
    /**
     * ユーザーの画像を取得
     */
    public function image(): MorphOne
    {
        return $this->morphOne(Image::class, 'imageable');
    }
}

リレーションの取得Retrieving the Relationship

データベーステーブルとモデルを定義すると、モデルを介してリレーションへアクセスできます。たとえば、投稿の画像を取得するには、image動的リレーションプロパティにアクセスします。Once your database table and models are defined, you may access the relationships via your models. For example, to retrieve the image for a post, we can access the image dynamic relationship property:

use App\Models\Post;

$post = Post::find(1);

$image = $post->image;

morphToの呼び出しを実行するメソッドの名前にアクセスすることで、ポリモーフィックモデルの親を取得できます。この場合、Imageモデルのimageableメソッドです。つまり、動的なリレーションプロパティとしてこのメソッドにアクセスします。You may retrieve the parent of the polymorphic model by accessing the name of the method that performs the call to morphTo. In this case, that is the imageable method on the Image model. So, we will access that method as a dynamic relationship property:

use App\Models\Image;

$image = Image::find(1);

$imageable = $image->imageable;

Imageモデルのimageableリレーションは、どのタイプのモデルがその画像を所有しているかに応じて、PostまたはUserインスタンスを返します。The imageable relation on the Image model will return either a Post or User instance, depending on which type of model owns the image.

キーの規約Key Conventions

必要に応じて、ポリモーフィックの子モデルで使用する"id"カラムと"type"カラムの名前をカスタマイズできます。その場合は、最初の引数として常にリレーション名をmorphToメソッドに渡してください。通常、この値はメソッド名と一致する必要があるため、PHPの__FUNCTION__定数を使用できます。If necessary, you may specify the name of the "id" and "type" columns utilized by your polymorphic child model. If you do so, ensure that you always pass the name of the relationship as the first argument to the morphTo method. Typically, this value should match the method name, so you may use PHP's __FUNCTION__ constant:

/**
 * 画像が属するモデルを取得
 */
public function imageable(): MorphTo
{
    return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id');
}

１対多（ポリモーフィック）One to Many (Polymorphic)

テーブル構造Table Structure

１対多のポリモーフィックリレーションは、一般的な１対多の関係に似ています。ただし、子モデルは単一のリレーションを使用して複数タイプのモデルに所属できます。たとえば、アプリケーションのユーザーが投稿やビデオに「コメント」できると想像してみてください。ポリモーフィックリレーションを使えば、投稿とビデオの両方のコメントを含めるため、commentsテーブル一つだけの使用ですみます。まず、この関係を構築するために必要なテーブル構造を調べてみましょう。A one-to-many polymorphic relation is similar to a typical one-to-many relation; however, the child model can belong to more than one type of model using a single association. For example, imagine users of your application can "comment" on posts and videos. Using polymorphic relationships, you may use a single comments table to contain comments for both posts and videos. First, let's examine the table structure required to build this relationship:

posts
    id - integer
    title - string
    body - text

videos
    id - integer
    title - string
    url - string

comments
    id - integer
    body - text
    commentable_id - integer
    commentable_type - string

モデル構造Model Structure

次に、この関係を構築するために必要なモデルの定義を見てみましょう。Next, let's examine the model definitions needed to build this relationship:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphTo;

class Comment extends Model
{
    /**
     * commentableな親モデルの取得（投稿かビデオ）
     */
    public function commentable(): MorphTo
    {
        return $this->morphTo();
    }
}

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphMany;

class Post extends Model
{
    /**
     * このポストの全コメント取得
     */
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }
}

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphMany;

class Video extends Model
{
    /**
     * このビデオの全コメント取得
     */
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }
}

リレーションの取得Retrieving the Relationship

データベーステーブルとモデルを定義したら、モデルの動的リレーションプロパティを介して関係へアクセスできます。たとえば、その投稿のすべてのコメントにアクセスするには、comments動的プロパティを使用できます。Once your database table and models are defined, you may access the relationships via your model's dynamic relationship properties. For example, to access all of the comments for a post, we can use the comments dynamic property:

use App\Models\Post;

$post = Post::find(1);

foreach ($post->comments as $comment) {
    // ...
}

morphToを呼び出し実行するメソッドの名前にアクセスすることで、ポリモーフィックな子モデルの親を取得することもできます。この場合、それはCommentモデルのcommentableメソッドです。では、コメントの親モデルへアクセスするために、動的リレーションプロパティとしてこのメソッドにアクセスしてみましょう。You may also retrieve the parent of a polymorphic child model by accessing the name of the method that performs the call to morphTo. In this case, that is the commentable method on the Comment model. So, we will access that method as a dynamic relationship property in order to access the comment's parent model:

use App\Models\Comment;

$comment = Comment::find(1);

$commentable = $comment->commentable;

Commentモデルのcommentableリレーションは、コメントの親であるモデルのタイプに応じて、PostまたはVideoインスタンスのいずれかを返します。The commentable relation on the Comment model will return either a Post or Video instance, depending on which type of model is the comment's parent.

One Of Many（ポリモーフィック）One of Many (Polymorphic)

あるモデルが多くの関連モデルを持つことがありますが、そのリレーションの「最新」または「最も古い」関連モデルを簡単に取得したい場合があります。例えば、Userモデルは多くのImageモデルと関連しており、ユーザーがアップロードした最新の画像を操作する便利な方法を定義したいとします。このような場合には、morphOneというリレーションタイプとofManyメソッドを組み合わせることで実現できます。Sometimes a model may have many related models, yet you want to easily retrieve the "latest" or "oldest" related model of the relationship. For example, a User model may be related to many Image models, but you want to define a convenient way to interact with the most recent image the user has uploaded. You may accomplish this using the morphOne relationship type combined with the ofMany methods:

/**
 * 最新のイメージを取得
 */
public function latestImage(): MorphOne
{
    return $this->morphOne(Image::class, 'imageable')->latestOfMany();
}

同様に、あるリレーションの「最も古い」、つまり最初の関連モデルを取得するメソッドを定義することもできます。Likewise, you may define a method to retrieve the "oldest", or first, related model of a relationship:

/**
 * ユーザーの最も古い画像を取得
 */
public function oldestImage(): MorphOne
{
    return $this->morphOne(Image::class, 'imageable')->oldestOfMany();
}

latestOfManyとoldestOfManyメソッドはデフォルトで、ソート可能なモデルの主キーに基づいて、最新または最古の関連モデルを取得します。しかし、時には、別のソート基準を使って、より大きなリレーションから単一モデルを取得したい場合も起きるでしょう。By default, the latestOfMany and oldestOfMany methods will retrieve the latest or oldest related model based on the model's primary key, which must be sortable. However, sometimes you may wish to retrieve a single model from a larger relationship using a different sorting criteria.

例えば、ofManyメソッドを使って、ユーザーが最も"Like"した画像を取得できます。ofManyメソッドは、ソート可能なカラムを第一引数に取り、関連するモデルを検索する際にどの集約関数（minまたはmax）を適用するかを指定します。For example, using the ofMany method, you may retrieve the user's most "liked" image. The ofMany method accepts the sortable column as its first argument and which aggregate function (min or max) to apply when querying for the related model:

/**
 * ユーザーの最も人気のある画像を取得
 */
public function bestImage(): MorphOne
{
    return $this->morphOne(Image::class, 'imageable')->ofMany('likes', 'max');
}

lightbulb Note: より高度な「一対多」リレーションを構築することも可能です。詳しくは、has one of manyのドキュメントを参照してください。[!NOTE]
It is possible to construct more advanced "one of many" relationships. For more information, please consult the has one of many documentation[#advanced-has-one-of-many-relationships].

多対多（ポリモーフィック）Many to Many (Polymorphic)

テーブル構造Table Structure

多対多のポリモーフィックリレーションは、"morph one"と"morph manyリレーションよりも少し複雑です。たとえば、PostモデルとVideoモデルは、Tagモデルとポリモーフィックな関係を共有できます。この状況で多対多のポリモーフィックリレーションを使用すると、アプリケーションで一意のタグのテーブルを一つ用意するだけで、投稿やビデオにそうしたタグを関係づけられます。まず、この関係を構築するために必要なテーブル構造を見てみましょう。Many-to-many polymorphic relations are slightly more complicated than "morph one" and "morph many" relationships. For example, a Post model and Video model could share a polymorphic relation to a Tag model. Using a many-to-many polymorphic relation in this situation would allow your application to have a single table of unique tags that may be associated with posts or videos. First, let's examine the table structure required to build this relationship:

posts
    id - integer
    name - string

videos
    id - integer
    name - string

tags
    id - integer
    name - string

taggables
    tag_id - integer
    taggable_id - integer
    taggable_type - string

lightbulb Note: ポリモーフィックな多対多のリレーションへに飛び込む前に、典型的な多対多の関係に関するドキュメントを読むとよいでしょう。[!NOTE]
Before diving into polymorphic many-to-many relationships, you may benefit from reading the documentation on typical many-to-many relationships[#many-to-many].

モデル構造Model Structure

これで、モデルの関係を定義する準備ができました。PostモデルとVideoモデルの両方に、基本のEloquentモデルクラスによって提供されるmorphToManyメソッドを呼び出すtagsメソッドを定義します。Next, we're ready to define the relationships on the models. The Post and Video models will both contain a tags method that calls the morphToMany method provided by the base Eloquent model class.

morphToManyメソッドは、関連モデルの名前と「リレーション名」を引数に取ります。中間テーブル名へ割り当てた名前とそれが持つキーに基づき、"taggable"と言う名前のリレーションで参照します。The morphToMany method accepts the name of the related model as well as the "relationship name". Based on the name we assigned to our intermediate table name and the keys it contains, we will refer to the relationship as "taggable":

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphToMany;

class Post extends Model
{
    /**
     * 投稿のすべてのタグを取得
     */
    public function tags(): MorphToMany
    {
        return $this->morphToMany(Tag::class, 'taggable');
    }
}

逆の関係の定義Defining the Inverse of the Relationship

次に、Tagモデルで、親になる可能性があるモデルごとにメソッドを定義する必要があります。したがって、この例ではpostsメソッドとvideosメソッドを定義します。これらのメソッドは両方とも、morphedByManyメソッドの結果を返す必要があります。Next, on the Tag model, you should define a method for each of its possible parent models. So, in this example, we will define a posts method and a videos method. Both of these methods should return the result of the morphedByMany method.

morphedByManyメソッドは、関連モデルの名前と「リレーション名」を引数に取ります。中間テーブル名へ付けた名前とそれが持つキーに基づいて、"taggable"と言う名前のリレーションで参照します。The morphedByMany method accepts the name of the related model as well as the "relationship name". Based on the name we assigned to our intermediate table name and the keys it contains, we will refer to the relationship as "taggable":

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphToMany;

class Tag extends Model
{
    /**
     * このタグを割り当てているすべての投稿を取得
     */
    public function posts(): MorphToMany
    {
        return $this->morphedByMany(Post::class, 'taggable');
    }

    /**
     * このタグを割り当てているすべての動画を取得
     */
    public function videos(): MorphToMany
    {
        return $this->morphedByMany(Video::class, 'taggable');
    }
}

リレーションの取得Retrieving the Relationship

データベーステーブルとモデルを定義したら、モデルを介してリレーションへアクセスできます。たとえば、ある投稿のすべてのタグにアクセスするには、tags動的リレーションプロパティを使用します。Once your database table and models are defined, you may access the relationships via your models. For example, to access all of the tags for a post, you may use the tags dynamic relationship property:

use App\Models\Post;

$post = Post::find(1);

foreach ($post->tags as $tag) {
    // ...
}

morphedByManyを呼び出し実行するメソッドの名前へアクセスすることで、ポリモーフィックな子モデルからポリモーフィックリレーションの親を取得できます。今回の場合、Tagモデルのpostsとvideosメソッドです。You may retrieve the parent of a polymorphic relation from the polymorphic child model by accessing the name of the method that performs the call to morphedByMany. In this case, that is the posts or videos methods on the Tag model:

use App\Models\Tag;

$tag = Tag::find(1);

foreach ($tag->posts as $post) {
    // ...
}

foreach ($tag->videos as $video) {
    // ...
}

カスタムポリモーフィックタイプCustom Polymorphic Types

デフォルトでLaravelは、完全修飾クラス名を使用して関連モデルの"type"を格納します。たとえば、CommentモデルがPostまたはVideoモデルに属する可能性がある前記の１対多関係の例では、デフォルトのcommentable_typeはApp\Models\PostかApp\Models\Videoのいずれかになります。ただし、これらの値をアプリケーションの内部構造から切り離したい場合も起きるでしょう。By default, Laravel will use the fully qualified class name to store the "type" of the related model. For instance, given the one-to-many relationship example above where a Comment model may belong to a Post or a Video model, the default commentable_type would be either App\Models\Post or App\Models\Video, respectively. However, you may wish to decouple these values from your application's internal structure.

たとえば、モデル名を"type"として使用する代わりに、postやvideoなどの単純な文字列を使用したい場合もあります。これにより、モデル名が変更されても、データベース内のポリモーフィックな「タイプ」カラムの値は有効なままになります。For example, instead of using the model names as the "type", we may use simple strings such as post and video. By doing so, the polymorphic "type" column values in our database will remain valid even if the models are renamed:

use Illuminate\Database\Eloquent\Relations\Relation;

Relation::enforceMorphMap([
    'post' => 'App\Models\Post',
    'video' => 'App\Models\Video',
]);

enforceMorphMap メソッドは、App\Providers\AppServiceProviderクラスのbootメソッドで呼び出すか、お好みであれば別のサービスプロバイダを作成してください。You may call the enforceMorphMap method in the boot method of your App\Providers\AppServiceProvider class or create a separate service provider if you wish.

モデルのgetMorphClassメソッドを使用して、実行時に指定したモデルのポリモーフィックのエイリアスを取得できます。逆に、Relation::getMorphedModelメソッドを使用して、ポリモーフィックのエイリアスへ関連付けた完全修飾クラス名を取得もできます。You may determine the morph alias of a given model at runtime using the model's getMorphClass method. Conversely, you may determine the fully-qualified class name associated with a morph alias using the Relation::getMorphedModel method:

use Illuminate\Database\Eloquent\Relations\Relation;

$alias = $post->getMorphClass();

$class = Relation::getMorphedModel($alias);

warning Warning! 既存のアプリケーションに「ポリモーフィックのマップ」を適用する場合、ポリモーフィックリレーションで使用していたそれまでの、完全修飾クラスを含むデータベース内の*_typeカラム値はすべて、「マップ」名に変換する必要が起きます。[!WARNING]
When adding a "morph map" to your existing application, every morphable *_type column value in your database that still contains a fully-qualified class will need to be converted to its "map" name.

動的リレーションDynamic Relationships

resolveRelationUsingメソッドを使用して、実行時にEloquentモデル間のリレーションを定義できます。通常のアプリケーション開発には推奨しませんが、Laravelパッケージの開発時には役立つでしょう。You may use the resolveRelationUsing method to define relations between Eloquent models at runtime. While not typically recommended for normal application development, this may occasionally be useful when developing Laravel packages.

resolveRelationUsingメソッドは、最初の引数に付けたいリレーション名を引数に取ります。メソッドの２番目の引数は、モデルインスタンスを引数に取り、有効なEloquentリレーションの定義を返すクロージャです。通常、サービスプロバイダのbootメソッド内で動的リレーションを設定する必要があります。The resolveRelationUsing method accepts the desired relationship name as its first argument. The second argument passed to the method should be a closure that accepts the model instance and returns a valid Eloquent relationship definition. Typically, you should configure dynamic relationships within the boot method of a service provider[/docs/{{version}}/providers]:

use App\Models\Order;
use App\Models\Customer;

Order::resolveRelationUsing('customer', function (Order $orderModel) {
    return $orderModel->belongsTo(Customer::class, 'customer_id');
});

warning Warning! 動的リレーションを定義するときは、常に明示的にキー名引数をEloquentリレーションメソッドの引数に渡してください。[!WARNING]
When defining dynamic relationships, always provide explicit key name arguments to the Eloquent relationship methods.

リレーションのクエリQuerying Relations

すべてのEloquentリレーションはメソッドを使い定義するので、関連モデルをロードするクエリを実際に実行しなくても、リレーションのインスタンスを取得するための、こうしたメソッドを呼び出しできます。さらに、すべてのタイプのEloquentリレーションは、クエリビルダとしても機能するため、データベースに対してSQLクエリを最終的に実行する前に、リレーションクエリに制約を連続してチェーンできます。Since all Eloquent relationships are defined via methods, you may call those methods to obtain an instance of the relationship without actually executing a query to load the related models. In addition, all types of Eloquent relationships also serve as query builders[/docs/{{version}}/queries], allowing you to continue to chain constraints onto the relationship query before finally executing the SQL query against your database.

たとえば、Userモデルに多くのPostモデルが関連付けられているブログアプリケーションを想像してみてください。For example, imagine a blog application in which a User model has many associated Post models:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class User extends Model
{
    /**
     * ユーザーのすべての投稿を取得
     */
    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

postsリレーションをクエリし、次のように関係に制約を追加できます。You may query the posts relationship and add additional constraints to the relationship like so:

use App\Models\User;

$user = User::find(1);

$user->posts()->where('active', 1)->get();

リレーションではLaravelクエリビルダメソッドのどれでも使用できるので、クエリビルダのドキュメントを調べ、使用可能な全メソッドを習んでください。You are able to use any of the Laravel query builder's[/docs/{{version}}/queries] methods on the relationship, so be sure to explore the query builder documentation to learn about all of the methods that are available to you.

リレーションの後でorWhere句をチェーンChaining orWhere Clauses After Relationships

上記の例で示したように、リレーションを照会するときは、その関係に制約を自由に追加できます。ただし、orWhere句をリレーションにチェーンする場合には注意が必要です。これは、orWhere句がリレーション制約と同じレベルで論理的にグループ化されるためです。As demonstrated in the example above, you are free to add additional constraints to relationships when querying them. However, use caution when chaining orWhere clauses onto a relationship, as the orWhere clauses will be logically grouped at the same level as the relationship constraint:

$user->posts()
        ->where('active', 1)
        ->orWhere('votes', '>=', 100)
        ->get();

上記の例は、以下のSQLを生成します。ご覧のとおり、or句は、100票を超える全ポストを返すようにクエリに指示します。クエリは特定のユーザーに制約されなくなりました。The example above will generate the following SQL. As you can see, the or clause instructs the query to return any post with greater than 100 votes. The query is no longer constrained to a specific user:

select *
from posts
where user_id = ? and active = 1 or votes >= 100

ほとんどの場合、論理グループを使用して、括弧内の条件付きチェックをグループ化する必要があります。In most situations, you should use logical groups[/docs/{{version}}/queries#logical-grouping] to group the conditional checks between parentheses:

use Illuminate\Database\Eloquent\Builder;

$user->posts()
        ->where(function (Builder $query) {
            return $query->where('active', 1)
                         ->orWhere('votes', '>=', 100);
        })
        ->get();

上記の例は、以下のSQLを生成します。論理グループ化によって制約が適切にグループ化され、クエリは特定のユーザーを制約したままであることに注意してください。The example above will produce the following SQL. Note that the logical grouping has properly grouped the constraints and the query remains constrained to a specific user:

select *
from posts
where user_id = ? and (active = 1 or votes >= 100)

リレーションメソッド対動的プロパティRelationship Methods vs. Dynamic Properties

Eloquentリレーションクエリへ制約を追加する必要がない場合は、プロパティであるかのようにリレーションにアクセスできます。たとえば、UserとPostのサンプルモデルを引き続き使用すると、次のようにユーザーのすべての投稿にアクセスできます。If you do not need to add additional constraints to an Eloquent relationship query, you may access the relationship as if it were a property. For example, continuing to use our User and Post example models, we may access all of a user's posts like so:

use App\Models\User;

$user = User::find(1);

foreach ($user->posts as $post) {
    // ...
}

動的リレーションプロパティは「遅延読み込み」を実行します。つまり、実際にアクセスしたときにのみリレーションデータが読み込まれます。このため、開発者はEagerロードを使用して、モデルのロード後にアクセスすることがわかっているリレーションを事前ロードすることがよくあります。Eagerロードにより、モデルのリレーションを読み込むために実行する必要のあるSQLクエリが大幅に削減されます。Dynamic relationship properties perform "lazy loading", meaning they will only load their relationship data when you actually access them. Because of this, developers often use eager loading[#eager-loading] to pre-load relationships they know will be accessed after loading the model. Eager loading provides a significant reduction in SQL queries that must be executed to load a model's relations.

リレーションの存在のクエリQuerying Relationship Existence

モデルレコードを取得するときは、リレーションのありなしに基づいて結果を制約したい場合もあるでしょう。たとえば、コメントが少なくとも１つあるすべてのブログ投稿を取得するとします。これを行うには、関係の名前をhasメソッドとorHasメソッドに渡すことができます。When retrieving model records, you may wish to limit your results based on the existence of a relationship. For example, imagine you want to retrieve all blog posts that have at least one comment. To do so, you may pass the name of the relationship to the has and orHas methods:

use App\Models\Post;

// コメントが少なくとも1つあるすべての投稿を取得
$posts = Post::has('comments')->get();

演算子とカウント数を指定して、クエリをさらにカスタマイズすることもできます。You may also specify an operator and count value to further customize the query:

// コメントが３つ以上あるすべての投稿を取得
$posts = Post::has('comments', '>=', 3)->get();

ネストしたhasステートメントは、「ドット」表記を使用して作成できます。たとえば、少なくとも1つの画像を持つコメントが、少なくとも1つあるすべての投稿を取得できます。Nested has statements may be constructed using "dot" notation. For example, you may retrieve all posts that have at least one comment that has at least one image:

// 画像付きのコメントが少なくとも1つある投稿を取得
$posts = Post::has('comments.images')->get();

さらに強力な機能が必要な場合は、whereHasメソッドとorWhereHasメソッドを使用して、コメントの内容の検査など、hasクエリに追加のクエリ制約を定義できます。If you need even more power, you may use the whereHas and orWhereHas methods to define additional query constraints on your has queries, such as inspecting the content of a comment:

use Illuminate\Database\Eloquent\Builder;

// code％と似ている単語を含むコメントが少なくとも１つある投稿を取得
$posts = Post::whereHas('comments', function (Builder $query) {
    $query->where('content', 'like', 'code%');
})->get();

// code％と似ている単語を含むコメントが１０件以上ある投稿を取得
$posts = Post::whereHas('comments', function (Builder $query) {
    $query->where('content', 'like', 'code%');
}, '>=', 10)->get();

warning Warning! Eloquentは現在、データベース間をまたぐリレーションの存在のクエリをサポートしていません。リレーションは同じデータベース内に存在する必要があります。[!WARNING]
Eloquent does not currently support querying for relationship existence across databases. The relationships must exist within the same database.

インライン関係存在クエリInline Relationship Existence Queries

リレーションのクエリに付加する単純な１つの条件で、リレーションの存在をクエリしたい場合は、whereRelation、orWhereRelation、whereMorphRelation、orWhereMorphRelationメソッドを使用するのが便利です。例として、承認されていないコメントを持つすべての投稿を照会してみましょう。If you would like to query for a relationship's existence with a single, simple where condition attached to the relationship query, you may find it more convenient to use the whereRelation, orWhereRelation, whereMorphRelation, and orWhereMorphRelation methods. For example, we may query for all posts that have unapproved comments:

use App\Models\Post;

$posts = Post::whereRelation('comments', 'is_approved', false)->get();

もちろん、クエリビルダのwhereメソッドの呼び出しと同様に、オペレータを指定することもできます。Of course, like calls to the query builder's where method, you may also specify an operator:

$posts = Post::whereRelation(
    'comments', 'created_at', '>=', now()->subHour()
)->get();

存在しないリレーションのクエリQuerying Relationship Absence

モデルレコードを取得するときに、リレーションがないことに基づいて結果を制限したい場合もあるでしょう。たとえば、コメントがないすべてのブログ投稿を取得する場合です。この場合は、リレーション名前をdoesntHaveメソッドやorDoesntHaveメソッドに渡します。When retrieving model records, you may wish to limit your results based on the absence of a relationship. For example, imagine you want to retrieve all blog posts that don't have any comments. To do so, you may pass the name of the relationship to the doesntHave and orDoesntHave methods:

use App\Models\Post;

$posts = Post::doesntHave('comments')->get();

さらに強力な機能が必要な場合は、whereDoesntHaveメソッドとorWhereDoesntHaveメソッドを使用して、コメントの内容の検査など、クエリ制約をdoesntHaveクエリへ追加できます。If you need even more power, you may use the whereDoesntHave and orWhereDoesntHave methods to add additional query constraints to your doesntHave queries, such as inspecting the content of a comment:

use Illuminate\Database\Eloquent\Builder;

$posts = Post::whereDoesntHave('comments', function (Builder $query) {
    $query->where('content', 'like', 'code%');
})->get();

「ドット」表記を使用して、ネストしたリレーションに対しクエリを実行できます。たとえば、次のクエリはコメントが無いすべての投稿を取得します。ただし、バンされていない著者からのコメントがある投稿は結果に含みます。You may use "dot" notation to execute a query against a nested relationship. For example, the following query will retrieve all posts that do not have comments; however, posts that have comments from authors that are not banned will be included in the results:

use Illuminate\Database\Eloquent\Builder;

$posts = Post::whereDoesntHave('comments.author', function (Builder $query) {
    $query->where('banned', 0);
})->get();

Morph ToリレーションのクエリQuerying Morph To Relationships

"morph to"リレーションの存在をクエリするには、whereHasMorphメソッドとwhereDoesntHaveMorphメソッドを使用します。これらのメソッドは、リレーション名を最初の引数に取ります。次にこのメソッドは、クエリに含める関連モデルの名前を引数に取ります。最後の引数は、リレーションクエリをカスタマイズするクロージャを指定します。To query the existence of "morph to" relationships, you may use the whereHasMorph and whereDoesntHaveMorph methods. These methods accept the name of the relationship as their first argument. Next, the methods accept the names of the related models that you wish to include in the query. Finally, you may provide a closure which customizes the relationship query:

use App\Models\Comment;
use App\Models\Post;
use App\Models\Video;
use Illuminate\Database\Eloquent\Builder;

// code%と似たタイトルの投稿や動画へ関連付けられたコメントを取得
$comments = Comment::whereHasMorph(
    'commentable',
    [Post::class, Video::class],
    function (Builder $query) {
        $query->where('title', 'like', 'code%');
    }
)->get();

// code%と似ていないタイトルの投稿と関連付けられたコメントを取得
$comments = Comment::whereDoesntHaveMorph(
    'commentable',
    Post::class,
    function (Builder $query) {
        $query->where('title', 'like', 'code%');
    }
)->get();

関連するポリモーフィックモデルの「タイプ」に基づいて、クエリ制約を追加したい場合もあるでしょう。whereHasMorphメソッドに渡したクロージャは、２番目の引数として$type値を受け取ります。この引数を使用すると、作成中のクエリの「タイプ」を調べることができます。You may occasionally need to add query constraints based on the "type" of the related polymorphic model. The closure passed to the whereHasMorph method may receive a $type value as its second argument. This argument allows you to inspect the "type" of the query that is being built:

use Illuminate\Database\Eloquent\Builder;

$comments = Comment::whereHasMorph(
    'commentable',
    [Post::class, Video::class],
    function (Builder $query, string $type) {
        $column = $type === Post::class ? 'content' : 'title';

        $query->where($column, 'like', 'code%');
    }
)->get();

関連するすべてのモデルのクエリQuerying All Related Models

指定可能なポリモーフィックモデルの配列を渡す代わりに、ワイルドカード値として*を指定できます。これによりLaravelへ、データベースから取得可能なすべてのポリモーフィックタイプを取得するように指示できます。Laravelは、この操作を実行するために追加のクエリを実行します。Instead of passing an array of possible polymorphic models, you may provide * as a wildcard value. This will instruct Laravel to retrieve all of the possible polymorphic types from the database. Laravel will execute an additional query in order to perform this operation:

use Illuminate\Database\Eloquent\Builder;

$comments = Comment::whereHasMorph('commentable', '*', function (Builder $query) {
    $query->where('title', 'like', 'foo%');
})->get();

関連するモデルの集計Aggregating Related Models

関連モデルのカウントCounting Related Models

実際にモデルをロードせずに、指定したリレーションの関連モデルの数をカウントしたい場合があります。このためには、withCountメソッドを使用します。withCountメソッドは結果のモデル上へ{リレーション}_count属性を作ります。Sometimes you may want to count the number of related models for a given relationship without actually loading the models. To accomplish this, you may use the withCount method. The withCount method will place a {relation}_count attribute on the resulting models:

use App\Models\Post;

$posts = Post::withCount('comments')->get();

foreach ($posts as $post) {
    echo $post->comments_count;
}

配列をwithCountメソッドに渡すことで、複数のリレーションの「カウント」を追加したり、クエリに制約を追加したりできます。By passing an array to the withCount method, you may add the "counts" for multiple relations as well as add additional constraints to the queries:

use Illuminate\Database\Eloquent\Builder;

$posts = Post::withCount(['votes', 'comments' => function (Builder $query) {
    $query->where('content', 'like', 'code%');
}])->get();

echo $posts[0]->votes_count;
echo $posts[0]->comments_count;

リレーションカウントの結果に別名を付け、同じリレーションの複数の集計もできます。You may also alias the relationship count result, allowing multiple counts on the same relationship:

use Illuminate\Database\Eloquent\Builder;

$posts = Post::withCount([
    'comments',
    'comments as pending_comments_count' => function (Builder $query) {
        $query->where('approved', false);
    },
])->get();

echo $posts[0]->comments_count;
echo $posts[0]->pending_comments_count;

遅延カウントロードDeferred Count Loading

loadCountメソッドを使用すると、親モデルがすでに取得された後にリレーションのカウントをロードできます。Using the loadCount method, you may load a relationship count after the parent model has already been retrieved:

$book = Book::first();

$book->loadCount('genres');

カウントクエリへクエリ制約を追加設定する必要がある場合は、カウントしたいリレーションをキーにした配列を渡すことができます。配列の値は、クエリビルダインスタンスを受け取るクロージャである必要があります。If you need to set additional query constraints on the count query, you may pass an array keyed by the relationships you wish to count. The array values should be closures which receive the query builder instance:

$book->loadCount(['reviews' => function (Builder $query) {
    $query->where('rating', 5);
}])

リレーションのカウントとカスタムSELECT文Relationship Counting and Custom Select Statements

withCountをselectステートメントと組み合わせる場合は、selectメソッドの後にwithCountを呼び出してください。If you're combining withCount with a select statement, ensure that you call withCount after the select method:

$posts = Post::select(['title', 'body'])
                ->withCount('comments')
                ->get();

その他の集計関数Other Aggregate Functions

Eloquentは、withCountメソッドに加えて、withMin、withMax、withAvg、withSum、withExistsメソッドも提供しています。これらのメソッドは、結果のモデルに{リレーション}_{集計機能}_{column}属性を配置します。In addition to the withCount method, Eloquent provides withMin, withMax, withAvg, withSum, and withExists methods. These methods will place a {relation}_{function}_{column} attribute on your resulting models:

use App\Models\Post;

$posts = Post::withSum('comments', 'votes')->get();

foreach ($posts as $post) {
    echo $post->comments_sum_votes;
}

集計関数の結果に別の名前を使用してアクセスしたい場合は、独自のエイリアスを指定します。If you wish to access the result of the aggregate function using another name, you may specify your own alias:

$posts = Post::withSum('comments as total_comments', 'votes')->get();

foreach ($posts as $post) {
    echo $post->total_comments;
}

loadCountメソッドと同様に、これらのメソッドの遅延バージョンも利用できます。こうした集計関数は、すでに取得しているEloquentモデルで実行します。Like the loadCount method, deferred versions of these methods are also available. These additional aggregate operations may be performed on Eloquent models that have already been retrieved:

$post = Post::first();

$post->loadSum('comments', 'votes');

これらの集約メソッドをselectステートメントと組み合わせる場合は、selectメソッドの後に集約メソッドのメソッドを呼び出してください。If you're combining these aggregate methods with a select statement, ensure that you call the aggregate methods after the select method:

$posts = Post::select(['title', 'body'])
                ->withExists('comments')
                ->get();

Morph Toリレーションの関連モデルのカウントCounting Related Models on Morph To Relationships

"morph to"リレーションとそのリレーションが返す可能性のあるさまざまなエンティティの関連モデル数をEagerロードしたい場合は、withメソッドをmorphToリレーションのmorphWithCountメソッドと組み合わせて使用​​します。If you would like to eager load a "morph to" relationship, as well as related model counts for the various entities that may be returned by that relationship, you may utilize the with method in combination with the morphTo relationship's morphWithCount method.

今回の例では、PhotoモデルとPostモデルがActivityFeedモデルを作成していると想定します。ActivityFeedモデルは、特定のActivityFeedインスタンスの親PhotoまたはPostモデルを取得できるようにするparentableという名前の"morph to"リレーションを定義すると想定します。さらに、Photoモデルには「多くの（have many）」Tagモデルがあり、Postモデルも「多くの（have many）」Commentモデルがあると仮定しましょう。In this example, let's assume that Photo and Post models may create ActivityFeed models. We will assume the ActivityFeed model defines a "morph to" relationship named parentable that allows us to retrieve the parent Photo or Post model for a given ActivityFeed instance. Additionally, let's assume that Photo models "have many" Tag models and Post models "have many" Comment models.

では、ActivityFeedインスタンスを取得し、各ActivityFeedインスタンスのparentable親モデルをEagerロードしましょう。さらに、各親の写真に関連付いているタグの数と、各親の投稿に関連付いているコメントの数を取得しましょう。Now, let's imagine we want to retrieve ActivityFeed instances and eager load the parentable parent models for each ActivityFeed instance. In addition, we want to retrieve the number of tags that are associated with each parent photo and the number of comments that are associated with each parent post:

use Illuminate\Database\Eloquent\Relations\MorphTo;

$activities = ActivityFeed::with([
    'parentable' => function (MorphTo $morphTo) {
        $morphTo->morphWithCount([
            Photo::class => ['tags'],
            Post::class => ['comments'],
        ]);
    }])->get();

遅延カウントロードDeferred Count Loading

すでにActivityFeedモデルを取得していて、アクティビティフィードに関連付いているさまざまなparentableモデルのネストしたリレーションのカウントをロードしたいとします。これを実現するには、loadMorphCountメソッドを使用します。Let's assume we have already retrieved a set of ActivityFeed models and now we would like to load the nested relationship counts for the various parentable models associated with the activity feeds. You may use the loadMorphCount method to accomplish this:

$activities = ActivityFeed::with('parentable')->get();

$activities->loadMorphCount('parentable', [
    Photo::class => ['tags'],
    Post::class => ['comments'],
]);

EagerロードEager Loading

Eloquentのリレーションにプロパティとしてアクセスする場合、関連モデルは「遅延ロード」されます。これは、最初にプロパティにアクセスするまでリレーションデータが実際にロードされないことを意味します。しかし、Eloquentは親モデルへのクエリ時に「Eagerロード」可能です。Eagerロードは、「Ｎ＋１」クエリ問題を軽減します。Ｎ＋１クエリ問題を説明するため、Authorモデルに「属する（belongs）」Bookモデルを考えてみましょう：When accessing Eloquent relationships as properties, the related models are "lazy loaded". This means the relationship data is not actually loaded until you first access the property. However, Eloquent can "eager load" relationships at the time you query the parent model. Eager loading alleviates the "N 1" query problem. To illustrate the N 1 query problem, consider a Book model that "belongs to" to an Author model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Book extends Model
{
    /**
     * その本を書いた著者を取得
     */
    public function author(): BelongsTo
    {
        return $this->belongsTo(Author::class);
    }
}

では、すべての本とその著者を取得しましょう。Now, let's retrieve all books and their authors:

use App\Models\Book;

$books = Book::all();

foreach ($books as $book) {
    echo $book->author->name;
}

このループは、データベーステーブル内のすべての本を取得するために１つのクエリを実行し、次に本の著者を取得するために各本に対して別のクエリを実行します。したがって、２５冊の本がある場合、上記のコードは２６のクエリを実行します。１回はもとの本の取得のため、それと各本の著者を取得するための２５回の追加クエリです。This loop will execute one query to retrieve all of the books within the database table, then another query for each book in order to retrieve the book's author. So, if we have 25 books, the code above would run 26 queries: one for the original book, and 25 additional queries to retrieve the author of each book.

ありがたいことに、Eagerロードを使用し、この操作を２つのクエリに減らすことができます。クエリを作成するときに、withメソッドを使用してどの関係をEagerロードするかを指定します。Thankfully, we can use eager loading to reduce this operation to just two queries. When building a query, you may specify which relationships should be eager loaded using the with method:

$books = Book::with('author')->get();

foreach ($books as $book) {
    echo $book->author->name;
}

この操作では、２クエリのみ実行します。１回はすべての本を取得するクエリで、もう１回はすべての本のすべての著者を取得するクエリです。For this operation, only two queries will be executed - one query to retrieve all of the books and one query to retrieve all of the authors for all of the books:

select * from books

select * from authors where id in (1, 2, 3, 4, 5, ...)

複数リレーションのEagerロードEager Loading Multiple Relationships

状況により、いくつか異なるリレーションをEagerロードする必要がおきます。これには、関係の配列をwithメソッドに渡すだけです。Sometimes you may need to eager load several different relationships. To do so, just pass an array of relationships to the with method:

$books = Book::with(['author', 'publisher'])->get();

ネストしたEagerロードNested Eager Loading

リレーションのリレーションをEagerロードするために、「ドット」構文が使えます。たとえば、本のすべての著者とすべての著者の個人的な連絡先をEagerロードしましょう。To eager load a relationship's relationships, you may use "dot" syntax. For example, let's eager load all of the book's authors and all of the author's personal contacts:

$books = Book::with('author.contacts')->get();

あるいは、withメソッドにネストした配列を指定し、ネストしたEagerロード関係を指定することもできます。これは、複数のネストした関係をEagerロードする場合に便利です。Alternatively, you may specify nested eager loaded relationships by providing a nested array to the with method, which can be convenient when eager loading multiple nested relationships:

$books = Book::with([
    'author' => [
        'contacts',
        'publisher',
    ],
])->get();

morphToリレーションのネストしたEagerロードNested Eager Loading morphTo Relationships

morphToリレーション、およびそのリレーションが返す可能性のあるさまざまなエンティティのネストしたリレーションをEagerロードしたい場合は、withメソッドをmorphToリレーションのmorphWithメソッドと組み合わせて使用​​します。この方法を説明するために、次のモデルについて考えてみましょう。If you would like to eager load a morphTo relationship, as well as nested relationships on the various entities that may be returned by that relationship, you may use the with method in combination with the morphTo relationship's morphWith method. To help illustrate this method, let's consider the following model:

<?php

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphTo;

class ActivityFeed extends Model
{
    /**
     * アクティビティフィードレコードの親を取得
     */
    public function parentable(): MorphTo
    {
        return $this->morphTo();
    }
}

この例では、Event、Photo、およびPostモデルがActivityFeedモデルを作成すると想定します。さらに、Eventモデルが「Calendarモデルに属し、PhotoモデルがTagモデルへ関連付けられ、PostモデルがAuthorモデルに属していると想定します。In this example, let's assume Event, Photo, and Post models may create ActivityFeed models. Additionally, let's assume that Event models belong to a Calendar model, Photo models are associated with Tag models, and Post models belong to an Author model.

これらのモデル定義とリレーションを使用して、ActivityFeedモデルインスタンスを取得し、すべてのparentableモデルとそれぞれのネストしたリレーションをEagerロードできます。Using these model definitions and relationships, we may retrieve ActivityFeed model instances and eager load all parentable models and their respective nested relationships:

use Illuminate\Database\Eloquent\Relations\MorphTo;

$activities = ActivityFeed::query()
    ->with(['parentable' => function (MorphTo $morphTo) {
        $morphTo->morphWith([
            Event::class => ['calendar'],
            Photo::class => ['tags'],
            Post::class => ['author'],
        ]);
    }])->get();

特定のカラムのEagerロードEager Loading Specific Columns

取得するリレーションのすべてのカラムが常に必要だとは限りません。このため、Eloquentはリレーションでどのカラムを取得するかを指定できます。You may not always need every column from the relationships you are retrieving. For this reason, Eloquent allows you to specify which columns of the relationship you would like to retrieve:

$books = Book::with('author:id,name,book_id')->get();

warning Warning! この機能を使用するときは、取得するカラムのリストで常にidカラムと関連する外部キーカラムを含める必要があります。[!WARNING]
When using this feature, you should always include the id column and any relevant foreign key columns in the list of columns you wish to retrieve.

デフォルトのEagerロードEager Loading by Default

モデルを取得するときに、常にいくつかのリレーションをロードしたい場合があります。実現するには、モデルに$withプロパティを定義します。Sometimes you might want to always load some relationships when retrieving a model. To accomplish this, you may define a $with property on the model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Book extends Model
{
    /**
     * 常にロードする必要があるリレーション
     *
     * @var array
     */
    protected $with = ['author'];

    /**
     * その本を書いた著者を取得
     */
    public function author(): BelongsTo
    {
        return $this->belongsTo(Author::class);
    }

    /**
     * 本のジャンルを取得
     */
    public function genre(): BelongsTo
    {
        return $this->belongsTo(Genre::class);
    }
}

一度のクエリで$withプロパティからのアイテムを削除する場合は、withoutメソッドを使用します。If you would like to remove an item from the $with property for a single query, you may use the without method:

$books = Book::without('author')->get();

一度のクエリに対し、$withプロパティ内のすべてのアイテムをオーバーライドしたい場合は、withOnlyメソッドが使えます。If you would like to override all items within the $with property for a single query, you may use the withOnly method:

$books = Book::withOnly('genre')->get();

Eagerロードの制約Constraining Eager Loads

リレーションをEagerロードするだけでなく、Eagerロードクエリへクエリ条件を追加指定したい場合もあります。そのためには、リレーションの配列をwithメソッドへ渡します。ここでの配列キーはリレーション名であり、配列値はEagerロードクエリへ制約を追加するクロージャです。Sometimes you may wish to eager load a relationship but also specify additional query conditions for the eager loading query. You can accomplish this by passing an array of relationships to the with method where the array key is a relationship name and the array value is a closure that adds additional constraints to the eager loading query:

use App\Models\User;
use Illuminate\Contracts\Database\Eloquent\Builder;

$users = User::with(['posts' => function (Builder $query) {
    $query->where('title', 'like', '%code%');
}])->get();

この例では、Eloquentは、投稿のtitleカラムにcodeという単語を含んでいる投稿のみをEagerロードします。他のクエリビルダメソッドを呼び出して、Eagerロード操作をさらにカスタマイズすることもできます。In this example, Eloquent will only eager load posts where the post's title column contains the word code. You may call other query builder[/docs/{{version}}/queries] methods to further customize the eager loading operation:

$users = User::with(['posts' => function (Builder $query) {
    $query->orderBy('created_at', 'desc');
}])->get();

morphToリレーションのEagerロードの制約Constraining Eager Loading of morphTo Relationships

morphToリレーションをEagerロードする場合、Eloquentは複数のクエリを実行して各タイプの関連モデルをフェッチします。MorphToリレーションのconstrainメソッドを使用して、これらの各クエリに制約を追加できます。If you are eager loading a morphTo relationship, Eloquent will run multiple queries to fetch each type of related model. You may add additional constraints to each of these queries using the MorphTo relation's constrain method:

use Illuminate\Database\Eloquent\Relations\MorphTo;

$comments = Comment::with(['commentable' => function (MorphTo $morphTo) {
    $morphTo->constrain([
        Post::class => function ($query) {
            $query->whereNull('hidden_at');
        },
        Video::class => function ($query) {
            $query->where('type', 'educational');
        },
    ]);
}])->get();

この例でEloquentは、非表示にされていない投稿とtype値が"educational"な動画のみをEagerロードします。In this example, Eloquent will only eager load posts that have not been hidden and videos that have a type value of "educational".

リレーションの存在時のEagerロードの制約Constraining Eager Loads With Relationship Existence

リレーションが存在するかどうかをチェックすると同時に、同じ条件に基づいてそのリレーションをロードする必要がある場合があります。例えば、与えられたクエリ条件と一致するPostモデルの子を持つUserモデルのみを取得し、同時に一致する投稿をEagerロードしたいことがあります。このような場合は、withWhereHasメソッドを使用します。You may sometimes find yourself needing to check for the existence of a relationship while simultaneously loading the relationship based on the same conditions. For example, you may wish to only retrieve User models that have child Post models matching a given query condition while also eager loading the matching posts. You may accomplish this using the withWhereHas method:

use App\Models\User;

$users = User::withWhereHas('posts', function ($query) {
    $query->where('featured', true);
})->get();

遅延EagerロードLazy Eager Loading

親モデルを取得した後に、リレーションをEagerロードしたい場合があります。たとえば、これは関連モデルをロードするかを動的に決定する必要がある場合で役立ちます。Sometimes you may need to eager load a relationship after the parent model has already been retrieved. For example, this may be useful if you need to dynamically decide whether to load related models:

use App\Models\Book;

$books = Book::all();

if ($someCondition) {
    $books->load('author', 'publisher');
}

Eagerロードクエリにクエリ制約を追加設定する必要がある場合は、ロードしたいリレーションをキーにした配列を渡します。配列の値は、クエリインスタンスを引数に受けるクロージャインスタンスの必要があります。If you need to set additional query constraints on the eager loading query, you may pass an array keyed by the relationships you wish to load. The array values should be closure instances which receive the query instance:

$author->load(['books' => function (Builder $query) {
    $query->orderBy('published_date', 'asc');
}]);

未ロードの場合にのみリレーションを読み込むには、loadMissingメソッドを使用します。To load a relationship only when it has not already been loaded, use the loadMissing method:

$book->loadMissing('author');

ネストした遅延EagerロードとmorphToNested Lazy Eager Loading and morphTo

morphToリレーション、およびそのリレーションが返す可能性のあるさまざまなエンティティのネストした関係をEagerロードしたい場合は、loadMorphメソッドを使用できます。If you would like to eager load a morphTo relationship, as well as nested relationships on the various entities that may be returned by that relationship, you may use the loadMorph method.

このメソッドは、最初の引数としてmorphToリレーション名を取り、２番目の引数としてモデル／リレーションペアの配列を受けます。このメソッドを説明するために、次のモデルについて考えてみましょう。This method accepts the name of the morphTo relationship as its first argument, and an array of model / relationship pairs as its second argument. To help illustrate this method, let's consider the following model:

<?php

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphTo;

class ActivityFeed extends Model
{
    /**
     * アクティビティフィードレコードの親を取得
     */
    public function parentable(): MorphTo
    {
        return $this->morphTo();
    }
}

この例では、Event、Photo、およびPostモデルがActivityFeedモデルを作成すると想定します。さらに、Eventモデルが「Calendarモデルに属し、PhotoモデルがTagモデルへ関連付けられ、PostモデルがAuthorモデルに属していると想定します。In this example, let's assume Event, Photo, and Post models may create ActivityFeed models. Additionally, let's assume that Event models belong to a Calendar model, Photo models are associated with Tag models, and Post models belong to an Author model.

これらのモデル定義とリレーションを使用して、ActivityFeedモデルインスタンスを取得し、すべてのparentableモデルとそれぞれのネストしたリレーションをEagerロードできます。Using these model definitions and relationships, we may retrieve ActivityFeed model instances and eager load all parentable models and their respective nested relationships:

$activities = ActivityFeed::with('parentable')
    ->get()
    ->loadMorph('parentable', [
        Event::class => ['calendar'],
        Photo::class => ['tags'],
        Post::class => ['author'],
    ]);

遅延ロードの防止Preventing Lazy Loading

前述したように、リレーションのEagerロードは、しばしばアプリケーションのパフォーマンスに大きなメリットをもたらします。そのため、ご希望であれば、Laravelにリレーションの遅延ロードを常に防ぐように指示できます。そのためには、Eloquentの基本モデルクラスが提供しているpreventLazyLoadingメソッドを呼び出します。一般的には、アプリケーションの AppServiceProvider クラスの boot メソッド内でこのメソッドを呼び出します。As previously discussed, eager loading relationships can often provide significant performance benefits to your application. Therefore, if you would like, you may instruct Laravel to always prevent the lazy loading of relationships. To accomplish this, you may invoke the preventLazyLoading method offered by the base Eloquent model class. Typically, you should call this method within the boot method of your application's AppServiceProvider class.

preventLazyLoading`メソッドは、遅延ロードを防止するかを示すオプションの論理値の引数を取ります。例として、運用環境以外では遅延ロードを無効にして、運用コードに遅延ロードするリレーションが誤って存在していても、運用環境では正常に機能し続けるようにしてみましょう。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:

use Illuminate\Database\Eloquent\Model;

/**
 * アプリケーションの全サービスの初期起動処理
 */
public function boot(): void
{
    Model::preventLazyLoading(! $this->app->isProduction());
}

遅延ロードを停止したあと、アプリケーションが任意のEloquentリレーションで遅延ロードしようとすると、EloquentはIlluminate\Database\LazyLoadingViolationException例外を投げます。After preventing lazy loading, Eloquent will throw a Illuminate\Database\LazyLoadingViolationException exception when your application attempts to lazy load any Eloquent relationship.

遅延ロード違反の動作は，handleLazyLoadingViolationsUsingメソッドを使ってカスタマイズできます。例えば、このメソッドを使って、アプリケーションの実行を例外で中断する代わりに、遅延ロード違反をログに記録するだけにするよう指示できます。You may customize the behavior of lazy loading violations using the handleLazyLoadingViolationsUsing method. For example, using this method, you may instruct lazy loading violations to only be logged instead of interrupting the application's execution with exceptions:

Model::handleLazyLoadingViolationUsing(function (Model $model, string $relation) {
    $class = $model::class;

    info("Attempted to lazy load [{$relation}] on model [{$class}].");
});

関連モデルの挿入と更新Inserting and Updating Related Models

saveメソッドThe save Method

Eloquentは、リレーションへ新しいモデルを追加する便利な手法を提供しています。たとえば、投稿に新しいコメントを追加する必要があるかもしれません。Commentモデルでpost_id属性を手作業で設定する代わりに、リレーションのsaveメソッドを使用してもコメントを追加できます。Eloquent provides convenient methods for adding new models to relationships. For example, perhaps you need to add a new comment to a post. Instead of manually setting the post_id attribute on the Comment model you may insert the comment using the relationship's save method:

use App\Models\Comment;
use App\Models\Post;

$comment = new Comment(['message' => 'A new comment.']);

$post = Post::find(1);

$post->comments()->save($comment);

動的プロパティとしてcomments関係へアクセスしなかったことに注意してください。代わりに、リレーションのインスタンスを取得するためにcommentsメソッドを呼び出しました。saveメソッドは、適切なpost_id値を新しいCommentモデルへ自動的に追加します。Note that we did not access the comments relationship as a dynamic property. Instead, we called the comments method to obtain an instance of the relationship. The save method will automatically add the appropriate post_id value to the new Comment model.

複数の関連モデルを保存する必要がある場合は、saveManyメソッドを使用します。If you need to save multiple related models, you may use the saveMany method:

$post = Post::find(1);

$post->comments()->saveMany([
    new Comment(['message' => 'A new comment.']),
    new Comment(['message' => 'Another new comment.']),
]);

saveメソッドとsaveManyメソッドは、指定したモデルインスタンスを保存しますが、親モデルへすでにロードしているメモリ内のリレーションには新しいモデルを追加保存しません。saveとsaveManyメソッドを使用した後にリレーションへアクセスしようと考えている場合は、refreshメソッドを使用してモデルとそのリレーションを再ロードするのを推奨します。The save and saveMany methods will persist the given model instances, but will not add the newly persisted models to any in-memory relationships that are already loaded onto the parent model. If you plan on accessing the relationship after using the save or saveMany methods, you may wish to use the refresh method to reload the model and its relationships:

$post->comments()->save($comment);

$post->refresh();

// 新しく保存されたコメントを含むすべてのコメント
$post->comments;

モデルと関係の再帰的保存Recursively Saving Models and Relationships

モデルとそれに関連するすべてのリレーションをsaveしたい場合は、pushメソッドを使用します。下記例では、Postモデルが、そのコメントとコメントの作成者とともに保存されます。If you would like to save your model and all of its associated relationships, you may use the push method. In this example, the Post model will be saved as well as its comments and the comment's authors:

$post = Post::find(1);

$post->comments[0]->message = 'Message';
$post->comments[0]->author->name = 'Author Name';

$post->push();

pushQuietlyメソッドは、イベントを発生させずに、モデルとそれに関連するリレーションを保存するために使用します。The pushQuietly method may be used to save a model and its associated relationships without raising any events:

$post->pushQuietly();

createメソッドThe create Method

saveメソッドとsaveManyメソッドに加え、属性の配列を受け取り、モデルを作成してデータベースに挿入するcreateメソッドも使用できます。saveとcreateの違いは、saveは完全なEloquentモデルインスタンスを受け入れるのに対し、createはプレーンなPHPのarrayを引数に取ることです。createメソッドは、新しく作成したモデルを返します。In addition to the save and saveMany methods, you may also use the create method, which accepts an array of attributes, creates a model, and inserts it into the database. The difference between save and create is that save accepts a full Eloquent model instance while create accepts a plain PHP array. The newly created model will be returned by the create method:

use App\Models\Post;

$post = Post::find(1);

$comment = $post->comments()->create([
    'message' => 'A new comment.',
]);

createManyメソッドを使用して、複数の関連モデルを作成できます。You may use the createMany method to create multiple related models:

$post = Post::find(1);

$post->comments()->createMany([
    ['message' => 'A new comment.'],
    ['message' => 'Another new comment.'],
]);

createQuietlyメソッドとcreateManyQuietlyメソッドを使用すると、イベントをディスパッチせずにモデルを作成できます。The createQuietly and createManyQuietly methods may be used to create a model(s) without dispatching any events:

$user = User::find(1);

$user->posts()->createQuietly([
    'title' => 'Post title.',
]);

$user->posts()->createManyQuietly([
    ['title' => 'First post.'],
    ['title' => 'Second post.'],
]);

findOrNew、firstOrNew、firstOrCreate、updateOrCreateメソッドを使用して関係のモデルを作成および更新することもできます。You may also use the findOrNew, firstOrNew, firstOrCreate, and updateOrCreate methods to create and update models on relationships[/docs/{{version}}/eloquent#upserts].

lightbulb Note: createメソッドを使用する前に、必ず複数代入のドキュメントを確認してください。[!NOTE]
Before using the create method, be sure to review the mass assignment[/docs/{{version}}/eloquent#mass-assignment] documentation.

Belongs ToリレーションBelongs To Relationships

子モデルを新しい親モデルに割り当てたい場合は、associateメソッドを使用します。下記例で、UserモデルはAccountモデルに対するbelongsToリレーションを定義しています。このassociateメソッドは、子モデルへ外部キーを設定します。If you would like to assign a child model to a new parent model, you may use the associate method. In this example, the User model defines a belongsTo relationship to the Account model. This associate method will set the foreign key on the child model:

use App\Models\Account;

$account = Account::find(10);

$user->account()->associate($account);

$user->save();

子モデルから親モデルを削除するには、dissociateメソッドを使用できます。このメソッドは、リレーションの外部キーをnullに設定します。To remove a parent model from a child model, you may use the dissociate method. This method will set the relationship's foreign key to null:

$user->account()->dissociate();

$user->save();

多対多リレーションMany to Many Relationships

関連付け／関連解除Attaching / Detaching

Eloquentは、多対多リレーションの作業をとても便利にする方法も提供しています。たとえば、ユーザーが多くの役割を持つことができ、役割が多くのユーザーを持つことができると想定してみましょう。attachメソッドを使用してリレーションの中間テーブルへレコードを挿入することで、ユーザーに役割を関連付けできます。Eloquent also provides methods to make working with many-to-many relationships more convenient. For example, let's imagine a user can have many roles and a role can have many users. You may use the attach method to attach a role to a user by inserting a record in the relationship's intermediate table:

use App\Models\User;

$user = User::find(1);

$user->roles()->attach($roleId);

モデルにリレーションを関連付けるときに、中間テーブルへ挿入する追加データの配列を渡すこともできます。When attaching a relationship to a model, you may also pass an array of additional data to be inserted into the intermediate table:

$user->roles()->attach($roleId, ['expires' => $expires]);

ユーザーから役割を削除する必要も起きるでしょう。多対多の関係レコードを削除するには、detachメソッドを使用します。detachメソッドは、中間テーブルから適切なレコードを削除します。ただし、両方のモデルはデータベースに残ります。Sometimes it may be necessary to remove a role from a user. To remove a many-to-many relationship record, use the detach method. The detach method will delete the appropriate record out of the intermediate table; however, both models will remain in the database:

// ユーザーから一つの役割を関連解除
$user->roles()->detach($roleId);

// ユーザーからすべての役割を関連解除
$user->roles()->detach();

使いやすいように、attachとdetachはIDの配列も引数に取れます。For convenience, attach and detach also accept arrays of IDs as input:

$user = User::find(1);

$user->roles()->detach([1, 2, 3]);

$user->roles()->attach([
    1 => ['expires' => $expires],
    2 => ['expires' => $expires],
]);

関連の同期Syncing Associations

syncメソッドを使用して、多対多の関連付けを構築することもできます。syncメソッドは、中間テーブルに配置するIDの配列を引数に取ります。指定した配列にないIDは、中間テーブルから削除されます。したがってこの操作が完了すると、指定した配列のIDのみが中間テーブルに残ります。You may also use the sync method to construct many-to-many associations. The sync method accepts an array of IDs to place on the intermediate table. Any IDs that are not in the given array will be removed from the intermediate table. So, after this operation is complete, only the IDs in the given array will exist in the intermediate table:

$user->roles()->sync([1, 2, 3]);

IDを使用して追加の中間テーブル値を渡すこともできます。You may also pass additional intermediate table values with the IDs:

$user->roles()->sync([1 => ['expires' => true], 2, 3]);

同期したモデルIDごとに同じ中間テーブルの値を挿入したい場合は、syncWithPivotValuesメソッドを使用できます。If you would like to insert the same intermediate table values with each of the synced model IDs, you may use the syncWithPivotValues method:

$user->roles()->syncWithPivotValues([1, 2, 3], ['active' => true]);

指定した配列から欠落している既存のIDを切り離したくない場合は、syncWithoutDetachingメソッドを使用します。If you do not want to detach existing IDs that are missing from the given array, you may use the syncWithoutDetaching method:

$user->roles()->syncWithoutDetaching([1, 2, 3]);

関連の切り替えToggling Associations

多対多リレーションは、指定した関連モデルIDの接続状態を「切り替える」、toggleメソッドも提供します。指定されたIDが現在関連づいている場合、そのIDを関連解除します。同様に現在関連していない場合は、関連付けます。The many-to-many relationship also provides a toggle method which "toggles" the attachment status of the given related model IDs. If the given ID is currently attached, it will be detached. Likewise, if it is currently detached, it will be attached:

$user->roles()->toggle([1, 2, 3]);

IDを使用して追加の中間テーブル値を渡すこともできます。You may also pass additional intermediate table values with the IDs:

$user->roles()->toggle([
    1 => ['expires' => true],
    2 => ['expires' => true],
]);

中間テーブルのレコード更新Updating a Record on the Intermediate Table

リレーションの中間テーブルの既存のカラムを更新する必要がある場合は、updateExistingPivotメソッドを使用します。このメソッドは、更新する中間レコードの外部キーと属性の配列を引数に取ります。If you need to update an existing row in your relationship's intermediate table, you may use the updateExistingPivot method. This method accepts the intermediate record foreign key and an array of attributes to update:

$user = User::find(1);

$user->roles()->updateExistingPivot($roleId, [
    'active' => false,
]);

親のタイムスタンプの更新Touching Parent Timestamps

Postに属するComment など、モデルが別のモデルとのbelongsToまたはbelongsToManyの関係を定義している場合、子モデルのが更新時に親のタイムスタンプも更新できると役立つ場合があります。When a model defines a belongsTo or belongsToMany relationship to another model, such as a Comment which belongs to a Post, it is sometimes helpful to update the parent's timestamp when the child model is updated.

たとえば、Commentモデルが更新されたときに、所有しているPostのupdated_atタイムスタンプを自動的に「更新」して、現在の日時を設定したい場合があるでしょう。これを行うには、子モデルの更新時にupdated_atタイムスタンプを更新する必要があるリレーションの名前を含むtouchesプロパティを子モデルに追加します。For example, when a Comment model is updated, you may want to automatically "touch" the updated_at timestamp of the owning Post so that it is set to the current date and time. To accomplish this, you may add a touches property to your child model containing the names of the relationships that should have their updated_at timestamps updated when the child model is updated:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Comment extends Model
{
    /**
     * 更新日時を更新すべき全リレーション
     *
     * @var array
     */
    protected $touches = ['post'];

    /**
     * コメントが属する投稿の取得
     */
    public function post(): BelongsTo
    {
        return $this->belongsTo(Post::class);
    }
}

warning Warning! 親モデルのタイムスタンプは、Eloquentのsaveメソッドを使用して子モデルを更新した場合にのみ更新されます。[!WARNING]
Parent model timestamps will only be updated if the child model is updated using Eloquent's save method.