Laravel master 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 several different types of relationships:

• １対１One To One[#one-to-one]
• １対多One To Many[#one-to-many]
• 多対多Many To Many[#many-to-many]
• Has Many ThroughHas Many Through[#has-many-through]
• ポリモーフィックリレーションPolymorphic Relations[#polymorphic-relations]
• ポリモーフィック関係の多対多Many To Many Polymorphic Relations[#many-to-many-polymorphic-relations]

リレーションの定義Defining Relationships

Eloquentのリレーション（関係）とはEloquentモデルクラスの関数として定義します。Eloquentモデル自身と同様にリレーションはパワフルなクエリビルダとして動作しますので、関数として定義している関係はパワフルなメソッドのチェーンとクエリ能力を提供できるのです。例として、posts関係に追加の制約をチェーンしてみましょう。Eloquent relationships are defined as functions on your Eloquent model classes. Since, like Eloquent models themselves, relationships also serve as powerful query builders[/docs/{{version}}/queries], defining relationships as functions provides powerful method chaining and querying capabilities. For example, we may chain additional constraints on this posts relationship:

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

リレーションの詳しい使い方へ進む前に、リレーションの各タイプをどのように定義するかを学びましょう。But, before diving too deep into using relationships, let's learn how to define each type.

１対１One To One

１対１関係が基本です。たとえばUserモデルはPhoneモデル一つと関係しているとしましょう。このリレーションを定義するには、phoneメソッドをUserモデルに設置します。phoneメソッドはベースのEloquentモデルクラスのhasOneメソッドを結果として返す必要があります。A one-to-one relationship is a very basic relation. For example, a User model might be associated with one Phone. To define this relationship, we place a phone method on the User model. The phone method should call the hasOne method and return its result:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

hasOneメソッドの最初の引数は関係するモデルの名前です。リレーションが定義できたらEloquentの動的プロパティを使って、関係したモデルを取得できます。動的プロパティによりモデル上のプロパティのようにリレーション関数にアクセスできます。The first argument passed to the hasOne method is the name of the related model. Once the relationship is defined, we may retrieve the related record using Eloquent's dynamic properties. Dynamic properties allow you to access relationship functions 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 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('App\Phone', 'foreign_key');

Eloquentは親のidカラム（もしくはカスタム$primaryKey）と一致する外部キーの値を持っていると仮定します。言い換えればEloquentはユーザのidカラムの値をPhoneレコードのuser_idカラムに存在しないか探します。リレーションで他のidを使いたければ、hadOneメソッドの第３引数でカスタムキーを指定してください。Additionally, Eloquent assumes that the foreign key should have a value matching the id (or the custom $primaryKey) 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 value other than id, you may pass a third argument to the hasOne method specifying your custom key:

return $this->hasOne('App\Phone', 'foreign_key', 'local_key');

逆の関係の定義Defining The Inverse Of The Relationship

これでUserからPhoneモデルへアクセスできるようになりました。今度はPhoneモデルからそれを所有しているUserへアクセスするリレーションを定義しましょう。hasOneの逆のリレーションを定義するには、belongsToメソッドを使います。So, we can access the Phone model from our User. Now, 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;

use Illuminate\Database\Eloquent\Model;

class Phone extends Model
{
    /**
     * この電話を所有するUserを取得
     */
    public function user()
    {
        return $this->belongsTo('App\User');
    }
}

上の例でEloquentはPhoneモデルのuser_idに一致するidを持つUserモデルを見つけようとします。Eloquentはリレーションメソッド名に_idのサフィックスを付けた名前をデフォルトの外部キー名とします。しかしPhoneモデルの外部キーがuser_idでなければ、belongsToメソッドの第２引数にカスタムキー名を渡してください。In the example above, Eloquent will try to match the user_id from the Phone model to an id on the User model. Eloquent determines the default foreign key name by examining the name of the relationship method and suffixing the method name with _id. 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:

/**
 * この電話を所有するUserを取得
 */
public function user()
{
    return $this->belongsTo('App\User', 'foreign_key');
}

親のモデルの主キーがidでない、もしくは子のモデルと違ったカラムで紐付けたい場合は、親テーブルのカスタムキー名をbelongsToメソッドの第３引数に渡してください。If your parent model does not use id as its primary key, or you wish to join the child model to a different column, you may pass a third argument to the belongsTo method specifying your parent table's custom key:

/**
 * この電話を所有するUserを取得
 */
public function user()
{
    return $this->belongsTo('App\User', 'foreign_key', 'other_key');
}

１対多One To Many

「１対多」リレーションは一つのモデルが他の多くのモデルを所有する関係を定義するために使います。ブログポストが多くのコメントを持つのが一例です。他のEloquentリレーションと同様に１対多リレーションはEloquentモデルの関数として定義します。A "one-to-many" relationship is used to define relationships where a single model owns any amount of other 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 placing a function on your Eloquent model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

EloquentはCommentモデルに対する外部キーを自動的に決めることを心に留めてください。規約によりEloquentは自分自身のモデル名の「スネークケース」に_idのサフィックスをつけた名前と想定します。ですから今回の例でEloquentはCommentモデルの外部キーをpost_idであると想定します。Remember, Eloquent will automatically determine the proper foreign key column on the Comment model. By convention, Eloquent will take the "snake case" name of the owning model and suffix it with _id. So, for this example, Eloquent will assume the foreign key on the Comment model is post_id.

リレーションを定義したらcommentsプロパティによりコメントのコレクションへアクセスできます。Eloquentは「動的プロパティ」を提供しているのでモデルのプロパティとして定義したリレーション関数へアクセスできることを覚えておきましょう。Once the relationship has been defined, we can access the collection of comments by accessing the comments property. Remember, since Eloquent provides "dynamic properties", we can access relationship functions as if they were defined as properties on the model:

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

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

もちろん全リレーションはクエリビルダとしても働きますから、commentsメソッドを呼び出すときにどのコメントを取得するのかという制約を追加でき、クエリに条件を続けてチェーンでつなげます。Of course, since all relationships also serve as query builders, you can add further constraints to which comments are retrieved by calling the comments method and continuing to chain conditions onto the query:

$comments = App\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('App\Comment', 'foreign_key');

return $this->hasMany('App\Comment', 'foreign_key', 'local_key');

１対多 (Inverse)One To Many (Inverse)

これでポストの全コメントにアクセスできます。今度はコメントから親のポストへアクセスできるようにしましょう。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 function on the child model which calls the belongsTo method:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    /**
     * このコメントを所有するポストを取得
     */
    public function post()
    {
        return $this->belongsTo('App\Post');
    }
}

リレーションが定義できたらCommentのPostモデルをpost動的プロパティにより取得しましょう。Once the relationship has been defined, we can retrieve the Post model for a Comment by accessing the post "dynamic property":

$comment = App\Comment::find(1);

echo $comment->post->title;

前例でEloquentはCommentモデルのpost_idと一致するidのPostモデルを見つけようとします。Eloquentはリレーションメソッドの名前に_idのサフィックスをつけた名前をデフォルトの外部キーとします。しかしCommentモデルの外部キーがpost_idでなければ、belongsToメソッドの第２引数にカスタムキー名を指定してください。In the example above, Eloquent will try to match the post_id from the Comment model to an id on the Post model. Eloquent determines the default foreign key name by examining the name of the relationship method and suffixing the method name with _id. However, if the foreign key on the Comment model is not post_id, you may pass a custom key name as the second argument to the belongsTo method:

/**
 * このコメントを所有するポストを取得
 */
public function post()
{
    return $this->belongsTo('App\Post', 'foreign_key');
}

親のモデルの主キーがidでない、もしくは子のモデルと違ったカラムで紐付けたい場合は、親テーブルのカスタムキー名をbelongsToメソッドの第３引数に渡してください。If your parent model does not use id as its primary key, or you wish to join the child model to a different column, you may pass a third argument to the belongsTo method specifying your parent table's custom key:

/**
 * このコメントを所有するポストを取得
 */
public function post()
{
    return $this->belongsTo('App\Post', 'foreign_key', 'other_key');
}

多対多Many To Many

多対多の関係はhasOneとhasManyリレーションよりも多少複雑な関係です。このような関係として、ユーザ(user)が多くの役目(roles)を持ち、役目(role)も大勢のユーザ(users)に共有されるという例が挙げられます。たとえば多くのユーザは"管理者"の役目を持っています。users、roles、role_userの３テーブルがこの関係には必要です。role_userテーブルは関係するモデル名をアルファベット順に並べたもので、user_idとrole_idを持つ必要があります。Many-to-many relations are slightly more complicated than hasOne and hasMany relationships. An example of such a relationship is a user with many roles, where the roles are also shared by other users. For example, many users may have the role of "Admin". 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 the user_id and role_id columns.

多対多リレーションはbelongsToManyメソッド呼び出しを記述することで定義します。例としてUserモデルにrolesメソッドを定義してみましょう。Many-to-many relationships are defined by writing a method that returns the result of the belongsToMany method. For example, let's define the roles method on our User model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * userに所属する役目を取得
     */
    public function roles()
    {
        return $this->belongsToMany('App\Role');
    }
}

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

$user = App\User::find(1);

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

もちろん他のリレーションタイプと同様にリレーションを制約するクエリをrolesに続けてチェーンすることができます。Of course, like all other relationship types, you may call the roles method to continue chaining query constraints onto the relationship:

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

前に述べたようにリレーションの結合テーブルの名前を決めるため、Eloquentは２つのモデル名をアルファベット順に結合します。しかしこの規約は自由にオーバーライドできます。belongsToManyメソッドの第２引数に渡してください。As mentioned previously, to determine the table name of the relationship's joining 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('App\Role', 'role_user');

結合テーブル名のカスタマイズに加えテーブルのキーカラム名をカスタマイズするには、belongsToManyメソッドに追加の引数を渡してください。第３引数はリレーションを定義しているモデルの外部キー名で、一方の第４引数には結合するモデルの外部キー名を渡します。In addition to customizing the name of the joining 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('App\Role', '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 simply place another call to belongsToMany on your related model. To continue our user roles example, let's define the users method on the Role model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Role extends Model
{
    /**
     * 役目を所有するユーザ
     */
    public function users()
    {
        return $this->belongsToMany('App\User');
    }
}

ご覧の通り一方のUserと全く同じ定義のリレーションです。違いはApp\Userモデルを参照していことです。同じbelongsToManyメソッドを使っているのですから、通常のテーブル名、キーカスタマイズのオプションは逆の多対多リレーションを定義するときでも全て使用できます。As you can see, the relationship is defined exactly the same as its User counterpart, with the exception of simply referencing the App\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 object has many Role objects that it is related to. After accessing this relationship, we may access the intermediate table using the pivot attribute on the models:

$user = App\User::find(1);

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

取得したそれぞれのRoleモデルは自動的にpivot属性と自動的に結合されます。この属性は中間テーブルを表すモデルを含んでおり、他のElouquentモデルと同様に使用できます。Notice that each Role model we retrieve is automatically assigned a pivot attribute. This attribute contains a model representing the intermediate table, and may be used like any other Eloquent model.

デフォルトでモデルキーはpivotオブジェクト上のものを表しています。中間テーブルがその他の属性を持っている場合、リレーションを定義するときに指定できます。By default, only the model keys will be present on the pivot object. If your pivot table contains extra attributes, you must specify them when defining the relationship:

return $this->belongsToMany('App\Role')->withPivot('column1', 'column2');

もし中間テーブルのcreated_at、updated_atタイムスタンプを自動的に保守したい場合は、withTimestampsメソッドをリレーション定義に付けてください。If you want your pivot table to have automatically maintained created_at and updated_at timestamps, use the withTimestamps method on the relationship definition:

return $this->belongsToMany('App\Role')->withTimestamps();

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

リレーション定義時に、wherePivotやwherePivotInを使い、belongsToManyが返す結果をフィルタリングすることも可能です。You can also filter the results returned by belongsToMany using the wherePivot and wherePivotIn methods when defining the relationship:

return $this->belongsToMany('App\Role')->wherePivot('approved', 1);

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

Has Many ThroughHas Many Through

has many through（〜経由の多対多）リレーションは、仲介するテーブルを通して直接関連付けしていないテーブルへアクセスするための、便利な近道を提供します。たとえばCountryモデルはUsersモデルを経由して、多くのPostsを所有することでしょう。テーブルは以下のような構成になります。The "has-many-through" relationship provides a convenient short-cut for accessing distant relations via an intermediate relation. For example, a Country model might have many Post models through an intermediate User model. In this example, you could easily gather all blog posts for a given country. Let's look at the tables required to define this relationship:

countries
    id - integer
    name - string

users
    id - integer
    country_id - integer
    name - string

posts
    id - integer
    user_id - integer
    title - string

たとえpostsテーブルにcountry_idが存在しなくても、hasManyThroughリレーションではCountryのPostへ$country->postsによりアクセスできます。このクエリを行うためにEloquentは仲介するusersテーブルのcountry_idを調べます。一致するユーザIDが存在していたらpostsテーブルのクエリに利用します。Though posts does not contain a country_id column, the hasManyThrough relation provides access to a country's posts via $country->posts. To perform this query, Eloquent inspects the country_id on the intermediate users table. After finding the matching user IDs, they are used to query the posts table.

ではリレーションのテーブル構造を理解したところで、Countryモデルを定義しましょう。Now that we have examined the table structure for the relationship, let's define it on the Country model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Country extends Model
{
    /**
     * この国の全ポストを取得
     */
    public function posts()
    {
        return $this->hasManyThrough('App\Post', 'App\User');
    }
}

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.

リレーションのクエリ実行時は、典型的な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, and the fifth argument is the local key:

class Country extends Model
{
    public function posts()
    {
        return $this->hasManyThrough(
            'App\Post', 'App\User',
            'country_id', 'user_id', 'id'
        );
    }
}

ポリモーフィック関係Polymorphic Relations

テーブル構造Table Structure

ポリモーフィック（Polymorphic：多様性）リレーションは一つの関係で、複数のモデルに所属させます。たとえば、アプリケーションのユーザがポスト(post:記事)と動画(video)に「コメント(comment)」できるとしましょう。最初にこのリレーションを構築するために必要な構造を確認してください。Polymorphic relations allow a model to belong to more than one other model on a single association. For example, imagine users of your application can "comment" both posts and videos. Using polymorphic relationships, you can use a single comments table for both of these scenarios. 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

commentsテーブルには２つの重要なcommentable_idとcommentable_typeカラムがあります。commentable_idカラムはポストかビデオのID値を保持します。一方のcommentable_typeカラムには、所有しているモデルのクラス名が保存されます。commentable関係にアクセスされた時に、所有してるのはどちらの「タイプ」のモデルなのか、ORMが決めるためにcommentable_typeカラムが存在しています。Two important columns to note are the commentable_id and commentable_type columns on the comments table. The commentable_id column will contain the ID value of the post or video, while the commentable_type column will contain the class name of the owning model. The commentable_type column is how the ORM determines which "type" of owning model to return when accessing the commentable relation.

モデル構造Model Structure

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

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    /**
     * 所有しているcommentableモデルの全取得
     */
    public function commentable()
    {
        return $this->morphTo();
    }
}

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

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

ポリモーフィックリレーションの取得Retrieving Polymorphic Relations

データベーステーブルとモデルが定義できたら、モデルを使いリレーションにアクセスできます。たとえば、あるポストの全コメントへアクセスするには、comments動的プロパティを使うだけです。Once your database table and models are defined, you may access the relationships via your models. For example, to access all of the comments for a post, we can simply use the comments dynamic property:

$post = App\Post::find(1);

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

morphToの呼び出しを行うメソッドの名前にアクセスすることにより、ポリモーフィック関連の所有者を取得することもできます。この例の場合、Commentモデルのcommentableメソッドです。では、このメソッドに動的プロパティによりアクセスしましょう。You may also retrieve the owner of a polymorphic relation from the polymorphic model by accessing the name of the method that performs the call to morphTo. In our case, that is the commentable method on the Comment model. So, we will access that method as a dynamic property:

$comment = App\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 owns the comment.

カスタムポリモーフィックリレーションCustom Polymorphic Types

関連付けられたモデルのタイプを保存するため、デフォルトでLaravelははっきりと区別できるクラス名を使います。たとえば上記の例で、CommentがPostかVideoに所属しているとすると、commentable_typeはデフォルトでApp\PostかApp\Videoのどちらかになるでしょう。しかし、データーベースはアプリケーションの内部構造と分離したいかと思います。その場合、リレーションの"morph map"を定義し、クラス名の代わりに使用する、各モデルに関連づいたテーブル名をEloquentへ指示することができます。By default, Laravel will use the fully qualified class name to store the type of the related model. For instance, given the example above where a Comment may belong to a Post or a Video, the default commentable_type would be either App\Post or App\Video, respectively. However, you may wish to decouple your database from your application's internal structure. In that case, you may define a relationship "morph map" to instruct Eloquent to use a custom name for each model instead of the class name:

use Illuminate\Database\Eloquent\Relations\Relation;

Relation::morphMap([
    'posts' => App\Post::class,
    'videos' => App\Video::class,
]);

morpMapは、AppServiceProviderのboot関数で登録できますし、お望みであれば独立したサービスプロバイダを作成し、その中で行うこともできます。You may register the morphMap in the boot function of your AppServiceProvider or create a separate service provider if you wish.

多対多 Polymorphic RelationsMany To Many Polymorphic Relations

テーブル構造Table Structure

伝統的なポリモーフィックリレーションに加え、「多対多」ポリモーフィックリレーションも指定することができます。たとえばブログのPostとVideoモデルはTagモデルに対するポリモーフィックリレーションを共有できます。多対多ポリモーフィックリレーションを使うことで、ブログポストとビデオの両者に所有されている一意のタグのリストを取得できます。最初にテーブル構造を確認しましょう。In addition to traditional polymorphic relations, you may also define "many-to-many" polymorphic relations. For example, a blog Post and Video model could share a polymorphic relation to a Tag model. Using a many-to-many polymorphic relation allows you to have a single list of unique tags that are shared across blog posts and videos. First, let's examine the table structure:

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

モデル構造Model Structure

次にモデルにその関係を用意しましょう。PostとVideoモデルは両方ともベースのEloquentクラスのmorphToManyメソッドを呼び出すtagsメソッドを持っています。Next, we're ready to define the relationships on the model. The Post and Video models will both have a tags method that calls the morphToMany method on the base Eloquent class:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    /**
     * ポストに対する全タグを取得
     */
    public function tags()
    {
        return $this->morphToMany('App\Tag', 'taggable');
    }
}

逆の関係の定義Defining The Inverse Of The Relationship

次にTagモデルで関係する各モデルに対するメソッドを定義する必要があります。ですからこの例の場合、postsメソッドとvideosメソッドを用意します。Next, on the Tag model, you should define a method for each of its related models. So, for this example, we will define a posts method and a videos method:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Tag extends Model
{
    /**
     * このタグをつけた全ポストの取得
     */
    public function posts()
    {
        return $this->morphedByMany('App\Post', 'taggable');
    }

    /**
     * このタグをつけた全ビデオの取得
     */
    public function videos()
    {
        return $this->morphedByMany('App\Video', '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 can simply use the tags dynamic property:

$post = App\Post::find(1);

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

さらにmorphedByManyを呼び出すメソッドの名前にアクセスし、ポリモーフィックモデルからポリモーフィックリレーションの所有者を取得することも可能です。この例の場合Tagモデルのpostsとvideosメソッドです。では動的プロパティーとしてメソッドを呼び出しましょう。You may also retrieve the owner of a polymorphic relation from the polymorphic model by accessing the name of the method that performs the call to morphedByMany. In our case, that is the posts or videos methods on the Tag model. So, you will access those methods as dynamic properties:

$tag = App\Tag::find(1);

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

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

Eloquentリレーションは全てメソッドとして定義され、リレーションのクエリを実際に記述しなくてもメソッドを呼び出すことでそのリレーションのインスタンスを取得できます。付け加えるなら、全タイプのEloquentリレーションもクエリビルダとしても動作し、データベースに対してSQLが最終的に実行される前にそのリレーションのクエリをチェーンで続けて記述できます。Since all types of Eloquent relationships are defined via functions, you may call those functions to obtain an instance of the relationship without actually executing the relationship queries. 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 against your database.

たとえばブログシステムで関連した多くのPostモデルを持つUserモデルを想像してください。For example, imagine a blog system in which a User model has many associated Post models:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザーの全ポストの取得
     */
    public function posts()
    {
        return $this->hasMany('App\Post');
    }
}

次のようにpostsリレーションのクエリに追加の制約を付け加えられます。You may query the posts relationship and add additional constraints to the relationship like so:

$user = App\User::find(1);

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

すべてのクエリビルダメソッドをリレーションで使用することも可能です。ですから、提供している全メソッドを学ぶために、クエリビルダのドキュメントを研究してください。You are able to use any of the query builder[/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.

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

Eloquentリレーションクエリに追加の制約を加える必要がなければ、シンプルにそのリレーションへプロパティーとしてアクセスできます。UserとPostの例を続けるとして、ユーザの全ポストには次のようにアクセスできます。If you do not need to add additional constraints to an Eloquent relationship query, you may simply 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:

$user = App\User::find(1);

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

動的プロパティーは「遅延ロード」されます。つまり実際にアクセスされた時にだけそのリレーションのデータはロードされます。そのため開発者は多くの場合にEagerローディングを使い、モデルをロードした後にアクセスするリレーションを前もってロードしておきます。Eagerロードはモデルのリレーションをロードするため実行されるSQLクエリを大幅に減らしてくれます。Dynamic properties are "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.

リレーションのクエリhip ExistenceQuerying Relationship Existence

関連付けたモデルのレコードに基づいて、モデルのレコードに対するマッチングを絞り込みたい場合もあるでしょう。たとえば最低でも一つのコメントを持つ、全ブログポストを取得したい場合を考えてください。これを行うためにはhasメソッドを使用します。When accessing the records for a model, 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 method:

// 最低１つのコメントを持つ全ポストの取得
$posts = App\Post::has('comments')->get();

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

// ３つ以上のコメントを持つ全ポストの取得
$posts = Post::has('comments', '>=', 3)->get();

ネストしたhas文は「ドット」記法で組立てられます。たとえば最低一つのコメントと評価を持つ全ポストを取得する場合です。Nested has statements may also be constructed using "dot" notation. For example, you may retrieve all posts that have at least one comment and vote:

// 最低１つのコメントと、それに対する評価を持つ全ポストの取得
$posts = Post::has('comments.votes')->get();

もっと強力な機能がお望みならばhasの問い合わせに"WHERE"で条件をつけるられる、whereHasやorWhereHasを利用して下さい。これらのメソッドによりリレーションの制約にカスタマイズした制約を追加できます。たとえばコメントの内容を調べることです。If you need even more power, you may use the whereHas and orWhereHas methods to put "where" conditions on your has queries. These methods allow you to add customized constraints to a relationship constraint, such as checking the content of a comment:

// like foo%の制約に一致する最低１つのコメントを持つ全ポストの取得
$posts = Post::whereHas('comments', function ($query) {
    $query->where('content', 'like', 'foo%');
})->get();

リレーションのクエリhip AbsenceQuerying Relationship Absence

モデルへアクセスする時に、結果をリレーションを持たないレコードに限定したい場合があります。たとえばブログで、コメントを持たないポストのみ全て取得したい場合です。これを行うには、doesntHaveメソッドにリレーション名を渡してください。When accessing the records for a model, 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 method:

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

もっと強力な機能がお望みなら、doesntHaveクエリに"WHERE"で条件を付けられる、whereDoesntHaveメソッドを使ってください。このメソッドはコメントの内容を調べるなど、リレーション制約にカスタム制約を付け加えられます。If you need even more power, you may use the whereDoesntHave method to put "where" conditions on your doesntHave queries. This method allows you to add customized constraints to a relationship constraint, such as checking the content of a comment:

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

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

リレーション結果の件数を実際にレコードを読み込むことなく知りたい場合は、withCountメソッドを使います。件数は結果のモデルの{リレーション名}_countカラムに格納されます。If you want to count the number of results from a relationship without actually loading them you may use the withCount method, which will place a {relation}_count column on your resulting models. For example:

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

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

クエリによる制約を加え、複数のリレーションの件数を取得することも可能です。You may add retrieve the "counts" for multiple relations as well as add constraints to the queries:

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

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

EagerローディングEager Loading

When accessing Eloquent relationships as properties, the relationship data is "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 is related to Author:When accessing Eloquent relationships as properties, the relationship data is "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 is related to Author:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

では全書籍とその著者を取得しましょう。Now, let's retrieve all books and their authors:

$books = App\Book::all();

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

このループではまず全ての本をテーブルから取得するために１クエリ実行され、それから著者をそれぞれの本について取得します。ですから２５冊あるならば、このループで２６クエリが発生します。This loop will execute 1 query to retrieve all of the books on the table, then another query for each book to retrieve the author. So, if we have 25 books, this loop would run 26 queries: 1 for the original book, and 25 additional queries to retrieve the author of each book.

ありがたいことにクエリの数を徹底的に減らすためにEagerローディングを使うことができます。withメソッドを使い指定してください。Thankfully, we can use eager loading to reduce this operation to just 2 queries. When querying, you may specify which relationships should be eager loaded using the with method:

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

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

この操作では２つだけしかクエリが実行されません。For this operation, only two queries will be executed:

select * from books

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

Eagerローディング Multiple RelationshipsEager Loading Multiple Relationships

一回の操作で異なった複数のリレーションをEagerローディングする必要がある場合もあります。その場合でも、ただwithメソッドに引数を追加で渡すだけです。Sometimes you may need to eager load several different relationships in a single operation. To do so, just pass additional arguments to the with method:

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

ネストしたEagerローディングNested Eager Loading

ネストしたリレーションをEagerロードする場合は「ドット」記法が使用できます。例としてEloquent文で全著者と著者個人のコンタクトも全部Eagerロードしてみましょう。To eager load nested 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 in one Eloquent statement:

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

Eagerロードへの制約Constraining Eager Loads

場合によりリレーションをEagerロードしたいが、Eagerロードクエリに制約を追加したい場合があります。例を見てください。Sometimes you may wish to eager load a relationship, but also specify additional query constraints for the eager loading query. Here's an example:

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

この例でEloquentは、titleカラムの内容にfirstという言葉を含むポストのみをEagerロードしています。もちろんEagerローディング操作をもっとカスタマイズするために、他のクエリビルダを呼び出すこともできます。In this example, Eloquent will only eager load posts where the post's title column contains the word first. Of course, you may call other query builder[/docs/{{version}}/queries] methods to further customize the eager loading operation:

$users = App\User::with(['posts' => function ($query) {
    $query->orderBy('created_at', 'desc');
}])->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:

$books = App\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:

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

関連したモデルの挿入／更新Inserting & Updating Related Models

SaveメソッドThe Save Method

Eloquentは新しいモデルをリレーションに追加するために便利なメソッドを用意しています。たとえばPostモデルに新しいCommentを挿入する必要がある場合です。Commentのpost_id属性を自分で設定する代わりに、リレーションのsaveメソッドで直接Commentを挿入できます。Eloquent provides convenient methods for adding new models to relationships. For example, perhaps you need to insert a new Comment for a Post model. Instead of manually setting the post_id attribute on the Comment, you may insert the Comment directly from the relationship's save method:

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

$post = App\Post::find(1);

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

動的プロパティーとしてcommentsリレーションにアクセスできない点には注意してください。代わりにリレーションの取得でcommentsメソッドを呼び出しています。saveメソッドは自動的に新しいCommentモデルのpost_idへ適した値を代入します。Notice 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 = App\Post::find(1);

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

CreateメソッドThe Create Method

saveとsaveManyメソッドに加え、createメソッドも使用できます。属性の配列を引数に受け付け、モデルを作成しデータベースへ挿入します。saveとcreateの違いはsaveが完全なEloquentモデルを受け付けるのに対し、createは普通のPHPの「配列」を受け付ける点です。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. Again, the difference between save and create is that save accepts a full Eloquent model instance while create accepts a plain PHP array:

$post = App\Post::find(1);

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

createメソッドを使用する前に属性の複数代入に関するドキュメントを読んでおいてください。Before using the create method, be sure to review the documentation on attribute mass assignment[/docs/{{version}}/eloquent#mass-assignment].

Belongs To関係Belongs To Relationships

belongsToリレーションを更新する場合はassociateメソッドを使います。このメソッドは子モデルへ外部キーをセットします。When updating a belongsTo relationship, you may use the associate method. This method will set the foreign key on the child model:

$account = App\Account::find(10);

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

$user->save();

belongsToリレーションを削除する場合はdissociateメソッドを使用します。このメソッドはリレーションの子モデルの外部キーをnullにします。When removing a belongsTo relationship, you may use the dissociate method. This method will set the relationship's foreign key to null:

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

$user->save();

多対多 RelationshipsMany To Many Relationships

attach／detachAttaching / Detaching

多対多リレーションを操作時により便利なように、Eloquentはヘルパメソッドをいくつか用意しています。例としてユーザが多くの役割りを持ち、役割も多くのユーザを持てる場合を考えてみましょう。モデルを結びつけている中間テーブルにレコードを挿入することにより、ユーザに役割を持たせるにはattachメソッドを使います。Eloquent also provides a few additional helper methods to make working with related models more convenient. For example, let's imagine a user can have many roles and a role can have many users. To attach a role to a user by inserting a record in the intermediate table that joins the models, use the attach method:

$user = App\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メソッドは中間テーブルから対応するレコードを削除します。しかし両方のモデルはデータベースに残ります。Of course, 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 remove 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 = App\User::find(1);

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

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

関連付けの同期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を削除したくない場合は、syncWithoutDetachingメソッドを使用します。If you do not want to detach existing IDs, you may use the syncWithoutDetaching method:

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

中間テーブルへの追加データ保存Saving Additional Data On A Pivot Table

多対多リレーションを操作する場合、saveメソッドの第２引数へ追加の中間テーブルの属性を指定できます。When working with a many-to-many relationship, the save method accepts an array of additional intermediate table attributes as its second argument:

App\User::find(1)->roles()->save($role, ['expires' => $expires]);

中間テーブルのレコード更新Updating A Record On A Pivot Table

中間テーブルに存在している行を更新する必要がある場合は、updateExistingPivotメソッドを使います。このメソッドは、中間テーブルの外部キーと更新する属性の配列を引数に取ります。If you need to update an existing row in your pivot table, you may use updateExistingPivot method. This method accepts the pivot record foreign key and an array of attributes to update:

$user = App\User::find(1);

$user->roles()->updateExistingPivot($roleId, $attributes);

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

CommentがPostに所属しているように、あるモデルが他のモデルに所属（belongsToもしくはbelongsToMany）しており、子のモデルが更新される時に親のタイムスタンプを更新できると便利なことがあります。たとえばCommentモデルが更新されたら、所有者のPostのupdated_atタイムスタンプを自動的に"touch"したい場合です。Eloquentなら簡単です。子のモデルにtouchesプロパティを追加しリレーション名を指定してください。When a model belongsTo or belongsToMany 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. For example, when a Comment model is updated, you may want to automatically "touch" the updated_at timestamp of the owning Post. Eloquent makes it easy. Just add a touches property containing the names of the relationships to the child model:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    /**
     * 全リレーションをtouch
     *
     * @var array
     */
    protected $touches = ['post'];

    /**
     * ポストに所属しているコメント取得
     */
    public function post()
    {
        return $this->belongsTo('App\Post');
    }
}

これでCommentが更新されると、所有しているPostのupdated_atカラムも同時に更新され、これによりPostモデルのいつのキャッシュを無効にするか判定できます。（訳注：最後の部分のみ、原文の意味が捉えきれません。）Now, when you update a Comment, the owning Post will have its updated_at column updated as well, making it more convenient to know when to invalidate a cache of the Post model:

$comment = App\Comment::find(1);

$comment->text = 'Edit to this comment!';

$comment->save();