Eloquent: Relationships

• Introduction
• Defining Relationships
  • One To One
  • One To Many
  • One To Many (Inverse) / Belongs To
  • Has One Of Many
  • Has One Through
  • Has Many Through
• Many To Many Relationships
  • Retrieving Intermediate Table Columns
  • Filtering Queries Via Intermediate Table Columns
  • Defining Custom Intermediate Table Models
• Polymorphic Relationships
  • One To One
  • One To Many
  • One Of Many
  • Many To Many
  • Custom Polymorphic Types
• Dynamic Relationships
• Querying Relations
  • Relationship Methods Vs. Dynamic Properties
  • Querying Relationship Existence
  • Querying Relationship Absence
  • Querying Morph To Relationships
• Aggregating Related Models
  • Counting Related Models
  • Other Aggregate Functions
  • Counting Related Models On Morph To Relationships
• Eager Loading
  • Constraining Eager Loads
  • Lazy Eager Loading
  • Preventing Lazy Loading
• Inserting & Updating Related Models
  • The save Method
  • The create Method
  • Belongs To Relationships
  • Many To Many Relationships
• Touching Parent Timestamps

Introduction

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 relationships are defined as methods on your Eloquent model classes. Since relationships also serve as powerful query builders, defining relationships as methods provides powerful method chaining and querying capabilities. For example, we may chain additional query constraints on this posts relationship:

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

But, before diving too deep into using relationships, let's learn how to define each type of relationship supported by Eloquent.

One To One

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * Get the phone associated with the user.
11     */
12    public function phone()
13    {
14        return $this->hasOne(Phone::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * Get the phone associated with the user.
11     */
12    public function phone()
13    {
14        return $this->hasOne(Phone::class);
15    }
16}

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:

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

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:

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

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:

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

Defining The Inverse Of The Relationship

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Phone extends Model
 8{
 9    /**
10     * Get the user that owns the phone.
11     */
12    public function user()
13    {
14        return $this->belongsTo(User::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Phone extends Model
 8{
 9    /**
10     * Get the user that owns the phone.
11     */
12    public function user()
13    {
14        return $this->belongsTo(User::class);
15    }
16}

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 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:

1/**
2 * Get the user that owns the phone.
3 */
4public function user()
5{
6    return $this->belongsTo(User::class, 'foreign_key');
7}
1/**
2 * Get the user that owns the phone.
3 */
4public function user()
5{
6    return $this->belongsTo(User::class, 'foreign_key');
7}

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:

1/**
2 * Get the user that owns the phone.
3 */
4public function user()
5{
6    return $this->belongsTo(User::class, 'foreign_key', 'owner_key');
7}
1/**
2 * Get the user that owns the phone.
3 */
4public function user()
5{
6    return $this->belongsTo(User::class, 'foreign_key', 'owner_key');
7}

One To Many

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Post extends Model
 8{
 9    /**
10     * Get the comments for the blog post.
11     */
12    public function comments()
13    {
14        return $this->hasMany(Comment::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Post extends Model
 8{
 9    /**
10     * Get the comments for the blog post.
11     */
12    public function comments()
13    {
14        return $this->hasMany(Comment::class);
15    }
16}

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.

Once the relationship method has been defined, we can access the collection 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:

1use App\Models\Post;
2 
3$comments = Post::find(1)->comments;
4 
5foreach ($comments as $comment) {
6    //
7}
1use App\Models\Post;
2 
3$comments = Post::find(1)->comments;
4 
5foreach ($comments as $comment) {
6    //
7}

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:

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

Like the hasOne method, you may also override the foreign and local keys by passing additional arguments to the hasMany method:

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

One To Many (Inverse) / Belongs To

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Comment extends Model
 8{
 9    /**
10     * Get the post that owns the comment.
11     */
12    public function post()
13    {
14        return $this->belongsTo(Post::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Comment extends Model
 8{
 9    /**
10     * Get the post that owns the comment.
11     */
12    public function post()
13    {
14        return $this->belongsTo(Post::class);
15    }
16}

Once the relationship has been defined, we can retrieve a comment's parent post by accessing the post "dynamic relationship property":

1use App\Models\Comment;
2 
3$comment = Comment::find(1);
4 
5return $comment->post->title;
1use App\Models\Comment;
2 
3$comment = Comment::find(1);
4 
5return $comment->post->title;

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

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:

1/**
2 * Get the post that owns the comment.
3 */
4public function post()
5{
6    return $this->belongsTo(Post::class, 'foreign_key');
7}
1/**
2 * Get the post that owns the comment.
3 */
4public function post()
5{
6    return $this->belongsTo(Post::class, 'foreign_key');
7}

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:

1/**
2 * Get the post that owns the comment.
3 */
4public function post()
5{
6    return $this->belongsTo(Post::class, 'foreign_key', 'owner_key');
7}
1/**
2 * Get the post that owns the comment.
3 */
4public function post()
5{
6    return $this->belongsTo(Post::class, 'foreign_key', 'owner_key');
7}

Default Models

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 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:

1/**
2 * Get the author of the post.
3 */
4public function user()
5{
6    return $this->belongsTo(User::class)->withDefault();
7}
1/**
2 * Get the author of the post.
3 */
4public function user()
5{
6    return $this->belongsTo(User::class)->withDefault();
7}

To populate the default model with attributes, you may pass an array or closure to the withDefault method:

 1/**
 2 * Get the author of the post.
 3 */
 4public function user()
 5{
 6    return $this->belongsTo(User::class)->withDefault([
 7        'name' => 'Guest Author',
 8    ]);
 9}
10 
11/**
12 * Get the author of the post.
13 */
14public function user()
15{
16    return $this->belongsTo(User::class)->withDefault(function ($user, $post) {
17        $user->name = 'Guest Author';
18    });
19}
 1/**
 2 * Get the author of the post.
 3 */
 4public function user()
 5{
 6    return $this->belongsTo(User::class)->withDefault([
 7        'name' => 'Guest Author',
 8    ]);
 9}
10 
11/**
12 * Get the author of the post.
13 */
14public function user()
15{
16    return $this->belongsTo(User::class)->withDefault(function ($user, $post) {
17        $user->name = 'Guest Author';
18    });
19}

Querying Belongs To Relationships

When querying for the children of a "belongs to" relationship, you may manually build the where clause to retrieve the corresponding Eloquent models:

1use App\Models\Post;
2 
3$posts = Post::where('user_id', $user->id)->get();
1use App\Models\Post;
2 
3$posts = Post::where('user_id', $user->id)->get();

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:

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

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:

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

Has One Of Many

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:

1/**
2 * Get the user's most recent order.
3 */
4public function latestOrder()
5{
6    return $this->hasOne(Order::class)->latestOfMany();
7}
1/**
2 * Get the user's most recent order.
3 */
4public function latestOrder()
5{
6    return $this->hasOne(Order::class)->latestOfMany();
7}

Likewise, you may define a method to retrieve the "oldest", or first, related model of a relationship:

1/**
2 * Get the user's oldest order.
3 */
4public function oldestOrder()
5{
6    return $this->hasOne(Order::class)->oldestOfMany();
7}
1/**
2 * Get the user's oldest order.
3 */
4public function oldestOrder()
5{
6    return $this->hasOne(Order::class)->oldestOfMany();
7}

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.

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:

1/**
2 * Get the user's largest order.
3 */
4public function largestOrder()
5{
6    return $this->hasOne(Order::class)->ofMany('price', 'max');
7}
1/**
2 * Get the user's largest order.
3 */
4public function largestOrder()
5{
6    return $this->hasOne(Order::class)->ofMany('price', 'max');
7}

Advanced Has One Of Many Relationships

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.

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:

 1/**
 2 * Get the current pricing for the product.
 3 */
 4public function currentPricing()
 5{
 6    return $this->hasOne(Price::class)->ofMany([
 7        'published_at' => 'max',
 8        'id' => 'max',
 9    ], function ($query) {
10        $query->where('published_at', '<', now());
11    });
12}
 1/**
 2 * Get the current pricing for the product.
 3 */
 4public function currentPricing()
 5{
 6    return $this->hasOne(Price::class)->ofMany([
 7        'published_at' => 'max',
 8        'id' => 'max',
 9    ], function ($query) {
10        $query->where('published_at', '<', now());
11    });
12}

Has One 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.

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:

 1mechanics
 2    id - integer
 3    name - string
 4 
 5cars
 6    id - integer
 7    model - string
 8    mechanic_id - integer
 9 
10owners
11    id - integer
12    name - string
13    car_id - integer
 1mechanics
 2    id - integer
 3    name - string
 4 
 5cars
 6    id - integer
 7    model - string
 8    mechanic_id - integer
 9 
10owners
11    id - integer
12    name - string
13    car_id - integer

Now that we have examined the table structure for the relationship, let's define the relationship on the Mechanic model:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Mechanic extends Model
 8{
 9    /**
10     * Get the car's owner.
11     */
12    public function carOwner()
13    {
14        return $this->hasOneThrough(Owner::class, Car::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Mechanic extends Model
 8{
 9    /**
10     * Get the car's owner.
11     */
12    public function carOwner()
13    {
14        return $this->hasOneThrough(Owner::class, Car::class);
15    }
16}

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.

Key Conventions

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:

 1class Mechanic extends Model
 2{
 3    /**
 4     * Get the car's owner.
 5     */
 6    public function carOwner()
 7    {
 8        return $this->hasOneThrough(
 9            Owner::class,
10            Car::class,
11            'mechanic_id', // Foreign key on the cars table...
12            'car_id', // Foreign key on the owners table...
13            'id', // Local key on the mechanics table...
14            'id' // Local key on the cars table...
15        );
16    }
17}
 1class Mechanic extends Model
 2{
 3    /**
 4     * Get the car's owner.
 5     */
 6    public function carOwner()
 7    {
 8        return $this->hasOneThrough(
 9            Owner::class,
10            Car::class,
11            'mechanic_id', // Foreign key on the cars table...
12            'car_id', // Foreign key on the owners table...
13            'id', // Local key on the mechanics table...
14            'id' // Local key on the cars table...
15        );
16    }
17}

Has Many Through

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. 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:

 1projects
 2    id - integer
 3    name - string
 4 
 5environments
 6    id - integer
 7    project_id - integer
 8    name - string
 9 
10deployments
11    id - integer
12    environment_id - integer
13    commit_hash - string
 1projects
 2    id - integer
 3    name - string
 4 
 5environments
 6    id - integer
 7    project_id - integer
 8    name - string
 9 
10deployments
11    id - integer
12    environment_id - integer
13    commit_hash - string

Now that we have examined the table structure for the relationship, let's define the relationship on the Project model:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Project extends Model
 8{
 9    /**
10     * Get all of the deployments for the project.
11     */
12    public function deployments()
13    {
14        return $this->hasManyThrough(Deployment::class, Environment::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Project extends Model
 8{
 9    /**
10     * Get all of the deployments for the project.
11     */
12    public function deployments()
13    {
14        return $this->hasManyThrough(Deployment::class, Environment::class);
15    }
16}

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.

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

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:

 1class Project extends Model
 2{
 3    public function deployments()
 4    {
 5        return $this->hasManyThrough(
 6            Deployment::class,
 7            Environment::class,
 8            'project_id', // Foreign key on the environments table...
 9            'environment_id', // Foreign key on the deployments table...
10            'id', // Local key on the projects table...
11            'id' // Local key on the environments table...
12        );
13    }
14}
 1class Project extends Model
 2{
 3    public function deployments()
 4    {
 5        return $this->hasManyThrough(
 6            Deployment::class,
 7            Environment::class,
 8            'project_id', // Foreign key on the environments table...
 9            'environment_id', // Foreign key on the deployments table...
10            'id', // Local key on the projects table...
11            'id' // Local key on the environments table...
12        );
13    }
14}

Many To Many Relationships

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

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.

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:

 1users
 2    id - integer
 3    name - string
 4 
 5roles
 6    id - integer
 7    name - string
 8 
 9role_user
10    user_id - integer
11    role_id - integer
 1users
 2    id - integer
 3    name - string
 4 
 5roles
 6    id - integer
 7    name - string
 8 
 9role_user
10    user_id - integer
11    role_id - integer

Model Structure

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * The roles that belong to the user.
11     */
12    public function roles()
13    {
14        return $this->belongsToMany(Role::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * The roles that belong to the user.
11     */
12    public function roles()
13    {
14        return $this->belongsToMany(Role::class);
15    }
16}

Once the relationship is defined, you may access the user's roles using the roles dynamic relationship property:

1use App\Models\User;
2 
3$user = User::find(1);
4 
5foreach ($user->roles as $role) {
6    //
7}
1use App\Models\User;
2 
3$user = User::find(1);
4 
5foreach ($user->roles as $role) {
6    //
7}

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:

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

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:

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

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:

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

Defining The Inverse Of The Relationship

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Role extends Model
 8{
 9    /**
10     * The users that belong to the role.
11     */
12    public function users()
13    {
14        return $this->belongsToMany(User::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Role extends Model
 8{
 9    /**
10     * The users that belong to the role.
11     */
12    public function users()
13    {
14        return $this->belongsToMany(User::class);
15    }
16}

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

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:

1use App\Models\User;
2 
3$user = User::find(1);
4 
5foreach ($user->roles as $role) {
6    echo $role->pivot->created_at;
7}
1use App\Models\User;
2 
3$user = User::find(1);
4 
5foreach ($user->roles as $role) {
6    echo $role->pivot->created_at;
7}

Notice that each Role model we retrieve is automatically assigned a pivot attribute. This attribute contains a model representing the intermediate table.

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:

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

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:

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

Customizing The pivot Attribute Name

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.

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:

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

Once the custom intermediate table attribute has been specified, you may access the intermediate table data using the customized name:

1$users = User::with('podcasts')->get();
2 
3foreach ($users->flatMap->podcasts as $podcast) {
4    echo $podcast->subscription->created_at;
5}
1$users = User::with('podcasts')->get();
2 
3foreach ($users->flatMap->podcasts as $podcast) {
4    echo $podcast->subscription->created_at;
5}

Filtering Queries Via Intermediate Table Columns

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:

 1return $this->belongsToMany(Role::class)
 2                ->wherePivot('approved', 1);
 3 
 4return $this->belongsToMany(Role::class)
 5                ->wherePivotIn('priority', [1, 2]);
 6 
 7return $this->belongsToMany(Role::class)
 8                ->wherePivotNotIn('priority', [1, 2]);
 9 
10return $this->belongsToMany(Podcast::class)
11                ->as('subscriptions')
12                ->wherePivotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
13 
14return $this->belongsToMany(Podcast::class)
15                ->as('subscriptions')
16                ->wherePivotNotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
17 
18return $this->belongsToMany(Podcast::class)
19                ->as('subscriptions')
20                ->wherePivotNull('expired_at');
21 
22return $this->belongsToMany(Podcast::class)
23                ->as('subscriptions')
24                ->wherePivotNotNull('expired_at');
 1return $this->belongsToMany(Role::class)
 2                ->wherePivot('approved', 1);
 3 
 4return $this->belongsToMany(Role::class)
 5                ->wherePivotIn('priority', [1, 2]);
 6 
 7return $this->belongsToMany(Role::class)
 8                ->wherePivotNotIn('priority', [1, 2]);
 9 
10return $this->belongsToMany(Podcast::class)
11                ->as('subscriptions')
12                ->wherePivotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
13 
14return $this->belongsToMany(Podcast::class)
15                ->as('subscriptions')
16                ->wherePivotNotBetween('created_at', ['2020-01-01 00:00:00', '2020-12-31 00:00:00']);
17 
18return $this->belongsToMany(Podcast::class)
19                ->as('subscriptions')
20                ->wherePivotNull('expired_at');
21 
22return $this->belongsToMany(Podcast::class)
23                ->as('subscriptions')
24                ->wherePivotNotNull('expired_at');

Defining Custom Intermediate Table Models

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 methods on the pivot model.

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Role extends Model
 8{
 9    /**
10     * The users that belong to the role.
11     */
12    public function users()
13    {
14        return $this->belongsToMany(User::class)->using(RoleUser::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Role extends Model
 8{
 9    /**
10     * The users that belong to the role.
11     */
12    public function users()
13    {
14        return $this->belongsToMany(User::class)->using(RoleUser::class);
15    }
16}

When defining the RoleUser model, you should extend the Illuminate\Database\Eloquent\Relations\Pivot class:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Relations\Pivot;
 6 
 7class RoleUser extends Pivot
 8{
 9    //
10}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Relations\Pivot;
 6 
 7class RoleUser extends Pivot
 8{
 9    //
10}

Custom Pivot Models And Incrementing IDs

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.

1/**
2 * Indicates if the IDs are auto-incrementing.
3 *
4 * @var bool
5 */
6public $incrementing = true;
1/**
2 * Indicates if the IDs are auto-incrementing.
3 *
4 * @var bool
5 */
6public $incrementing = true;

Polymorphic Relationships

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

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:

 1posts
 2    id - integer
 3    name - string
 4 
 5users
 6    id - integer
 7    name - string
 8 
 9images
10    id - integer
11    url - string
12    imageable_id - integer
13    imageable_type - string
 1posts
 2    id - integer
 3    name - string
 4 
 5users
 6    id - integer
 7    name - string
 8 
 9images
10    id - integer
11    url - string
12    imageable_id - integer
13    imageable_type - string

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:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Image extends Model
 8{
 9    /**
10     * Get the parent imageable model (user or post).
11     */
12    public function imageable()
13    {
14        return $this->morphTo();
15    }
16}
17 
18class Post extends Model
19{
20    /**
21     * Get the post's image.
22     */
23    public function image()
24    {
25        return $this->morphOne(Image::class, 'imageable');
26    }
27}
28 
29class User extends Model
30{
31    /**
32     * Get the user's image.
33     */
34    public function image()
35    {
36        return $this->morphOne(Image::class, 'imageable');
37    }
38}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Image extends Model
 8{
 9    /**
10     * Get the parent imageable model (user or post).
11     */
12    public function imageable()
13    {
14        return $this->morphTo();
15    }
16}
17 
18class Post extends Model
19{
20    /**
21     * Get the post's image.
22     */
23    public function image()
24    {
25        return $this->morphOne(Image::class, 'imageable');
26    }
27}
28 
29class User extends Model
30{
31    /**
32     * Get the user's image.
33     */
34    public function image()
35    {
36        return $this->morphOne(Image::class, 'imageable');
37    }
38}

Retrieving The Relationship

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:

1use App\Models\Post;
2 
3$post = Post::find(1);
4 
5$image = $post->image;
1use App\Models\Post;
2 
3$post = Post::find(1);
4 
5$image = $post->image;

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:

1use App\Models\Image;
2 
3$image = Image::find(1);
4 
5$imageable = $image->imageable;
1use App\Models\Image;
2 
3$image = Image::find(1);
4 
5$imageable = $image->imageable;

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

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:

1/**
2 * Get the model that the image belongs to.
3 */
4public function imageable()
5{
6    return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id');
7}
1/**
2 * Get the model that the image belongs to.
3 */
4public function imageable()
5{
6    return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id');
7}

One To Many (Polymorphic)

Table Structure

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:

 1posts
 2    id - integer
 3    title - string
 4    body - text
 5 
 6videos
 7    id - integer
 8    title - string
 9    url - string
10 
11comments
12    id - integer
13    body - text
14    commentable_id - integer
15    commentable_type - string
 1posts
 2    id - integer
 3    title - string
 4    body - text
 5 
 6videos
 7    id - integer
 8    title - string
 9    url - string
10 
11comments
12    id - integer
13    body - text
14    commentable_id - integer
15    commentable_type - string

Model Structure

Next, let's examine the model definitions needed to build this relationship:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Comment extends Model
 8{
 9    /**
10     * Get the parent commentable model (post or video).
11     */
12    public function commentable()
13    {
14        return $this->morphTo();
15    }
16}
17 
18class Post extends Model
19{
20    /**
21     * Get all of the post's comments.
22     */
23    public function comments()
24    {
25        return $this->morphMany(Comment::class, 'commentable');
26    }
27}
28 
29class Video extends Model
30{
31    /**
32     * Get all of the video's comments.
33     */
34    public function comments()
35    {
36        return $this->morphMany(Comment::class, 'commentable');
37    }
38}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Comment extends Model
 8{
 9    /**
10     * Get the parent commentable model (post or video).
11     */
12    public function commentable()
13    {
14        return $this->morphTo();
15    }
16}
17 
18class Post extends Model
19{
20    /**
21     * Get all of the post's comments.
22     */
23    public function comments()
24    {
25        return $this->morphMany(Comment::class, 'commentable');
26    }
27}
28 
29class Video extends Model
30{
31    /**
32     * Get all of the video's comments.
33     */
34    public function comments()
35    {
36        return $this->morphMany(Comment::class, 'commentable');
37    }
38}

Retrieving The Relationship

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:

1use App\Models\Post;
2 
3$post = Post::find(1);
4 
5foreach ($post->comments as $comment) {
6    //
7}
1use App\Models\Post;
2 
3$post = Post::find(1);
4 
5foreach ($post->comments as $comment) {
6    //
7}

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:

1use App\Models\Comment;
2 
3$comment = Comment::find(1);
4 
5$commentable = $comment->commentable;
1use App\Models\Comment;
2 
3$comment = Comment::find(1);
4 
5$commentable = $comment->commentable;

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

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:

1/**
2 * Get the user's most recent image.
3 */
4public function latestImage()
5{
6    return $this->morphOne(Image::class, 'imageable')->latestOfMany();
7}
1/**
2 * Get the user's most recent image.
3 */
4public function latestImage()
5{
6    return $this->morphOne(Image::class, 'imageable')->latestOfMany();
7}

Likewise, you may define a method to retrieve the "oldest", or first, related model of a relationship:

1/**
2 * Get the user's oldest image.
3 */
4public function oldestImage()
5{
6    return $this->morphOne(Image::class, 'imageable')->oldestOfMany();
7}
1/**
2 * Get the user's oldest image.
3 */
4public function oldestImage()
5{
6    return $this->morphOne(Image::class, 'imageable')->oldestOfMany();
7}

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.

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:

1/**
2 * Get the user's most popular image.
3 */
4public function bestImage()
5{
6    return $this->morphOne(Image::class, 'imageable')->ofMany('likes', 'max');
7}
1/**
2 * Get the user's most popular image.
3 */
4public function bestImage()
5{
6    return $this->morphOne(Image::class, 'imageable')->ofMany('likes', 'max');
7}

Many To Many (Polymorphic)

Table Structure

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:

 1posts
 2    id - integer
 3    name - string
 4 
 5videos
 6    id - integer
 7    name - string
 8 
 9tags
10    id - integer
11    name - string
12 
13taggables
14    tag_id - integer
15    taggable_id - integer
16    taggable_type - string
 1posts
 2    id - integer
 3    name - string
 4 
 5videos
 6    id - integer
 7    name - string
 8 
 9tags
10    id - integer
11    name - string
12 
13taggables
14    tag_id - integer
15    taggable_id - integer
16    taggable_type - string

Model Structure

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.

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":

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Post extends Model
 8{
 9    /**
10     * Get all of the tags for the post.
11     */
12    public function tags()
13    {
14        return $this->morphToMany(Tag::class, 'taggable');
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Post extends Model
 8{
 9    /**
10     * Get all of the tags for the post.
11     */
12    public function tags()
13    {
14        return $this->morphToMany(Tag::class, 'taggable');
15    }
16}

Defining The Inverse Of The Relationship

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.

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":

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Tag extends Model
 8{
 9    /**
10     * Get all of the posts that are assigned this tag.
11     */
12    public function posts()
13    {
14        return $this->morphedByMany(Post::class, 'taggable');
15    }
16 
17    /**
18     * Get all of the videos that are assigned this tag.
19     */
20    public function videos()
21    {
22        return $this->morphedByMany(Video::class, 'taggable');
23    }
24}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class Tag extends Model
 8{
 9    /**
10     * Get all of the posts that are assigned this tag.
11     */
12    public function posts()
13    {
14        return $this->morphedByMany(Post::class, 'taggable');
15    }
16 
17    /**
18     * Get all of the videos that are assigned this tag.
19     */
20    public function videos()
21    {
22        return $this->morphedByMany(Video::class, 'taggable');
23    }
24}

Retrieving The Relationship

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:

1use App\Models\Post;
2 
3$post = Post::find(1);
4 
5foreach ($post->tags as $tag) {
6    //
7}
1use App\Models\Post;
2 
3$post = Post::find(1);
4 
5foreach ($post->tags as $tag) {
6    //
7}

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:

 1use App\Models\Tag;
 2 
 3$tag = Tag::find(1);
 4 
 5foreach ($tag->posts as $post) {
 6    //
 7}
 8 
 9foreach ($tag->videos as $video) {
10    //
11}
 1use App\Models\Tag;
 2 
 3$tag = Tag::find(1);
 4 
 5foreach ($tag->posts as $post) {
 6    //
 7}
 8 
 9foreach ($tag->videos as $video) {
10    //
11}

Custom Polymorphic Types

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.

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:

1use Illuminate\Database\Eloquent\Relations\Relation;
2 
3Relation::enforceMorphMap([
4    'post' => 'App\Models\Post',
5    'video' => 'App\Models\Video',
6]);
1use Illuminate\Database\Eloquent\Relations\Relation;
2 
3Relation::enforceMorphMap([
4    'post' => 'App\Models\Post',
5    'video' => 'App\Models\Video',
6]);

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.

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:

1use Illuminate\Database\Eloquent\Relations\Relation;
2 
3$alias = $post->getMorphClass();
4 
5$class = Relation::getMorphedModel($alias);
1use Illuminate\Database\Eloquent\Relations\Relation;
2 
3$alias = $post->getMorphClass();
4 
5$class = Relation::getMorphedModel($alias);

Dynamic Relationships

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.

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:

1use App\Models\Order;
2use App\Models\Customer;
3 
4Order::resolveRelationUsing('customer', function ($orderModel) {
5    return $orderModel->belongsTo(Customer::class, 'customer_id');
6});
1use App\Models\Order;
2use App\Models\Customer;
3 
4Order::resolveRelationUsing('customer', function ($orderModel) {
5    return $orderModel->belongsTo(Customer::class, 'customer_id');
6});

Querying Relations

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, allowing you to continue to chain constraints onto the relationship query before finally executing the SQL query against your database.

For example, imagine a blog application in which a User model has many associated Post models:

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * Get all of the posts for the user.
11     */
12    public function posts()
13    {
14        return $this->hasMany(Post::class);
15    }
16}
 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6 
 7class User extends Model
 8{
 9    /**
10     * Get all of the posts for the user.
11     */
12    public function posts()
13    {
14        return $this->hasMany(Post::class);
15    }
16}