![]()
WARNING You're browsing the documentation for an upcoming version of Laravel. The documentation and features of this release are subject to change.
Eloquent: Relationships
- Introduction
- Defining Relationships
- Many To Many Relationships
- Polymorphic Relationships
- Dynamic Relationships
- Querying Relations
- Aggregating Related Models
- Eager Loading
- Inserting & Updating Related Models
- 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:$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 onePhone
model. To define this relationship, we will place aphone
method on theUser
model. Thephone
method should call thehasOne
method and return its result. ThehasOne
method is available to your model via the model'sIlluminate\Database\Eloquent\Model
base class:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * Get the phone associated with the user. */ public function phone() { return $this->hasOne(Phone::class); } }
The first argument passed to the
hasOne
method is the name of the related model class. Once the relationship is defined, we may retrieve the related record using Eloquent's dynamic properties. Dynamic properties allow you to access relationship methods as if they were properties defined on the model:$phone = User::find(1)->phone;
Eloquent determines the foreign key of the relationship based on the parent model name. In this case, the
Phone
model is automatically assumed to have auser_id
foreign key. If you wish to override this convention, you may pass a second argument to thehasOne
method:return $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 theuser_id
column of thePhone
record. If you would like the relationship to use a primary key value other thanid
or your model's$primaryKey
property, you may pass a third argument to thehasOne
method:return $this->hasOne(Phone::class, 'foreign_key', 'local_key');
Defining The Inverse Of The Relationship
So, we can access the
Phone
model from ourUser
model. Next, let's define a relationship on thePhone
model that will let us access the user that owns the phone. We can define the inverse of ahasOne
relationship using thebelongsTo
method:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Phone extends Model { /** * Get the user that owns the phone. */ public function user() { return $this->belongsTo(User::class); } }
When invoking the
user
method, Eloquent will attempt to find aUser
model that has anid
which matches theuser_id
column on thePhone
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 thePhone
model has auser_id
column. However, if the foreign key on thePhone
model is notuser_id
, you may pass a custom key name as the second argument to thebelongsTo
method:/** * Get the user that owns the phone. */ public function user() { return $this->belongsTo(User::class, 'foreign_key'); }
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 thebelongsTo
method specifying the parent table's custom key:/** * Get the user that owns the phone. */ public function user() { return $this->belongsTo(User::class, 'foreign_key', 'owner_key'); }
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:
<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Post extends Model { /** * Get the comments for the blog post. */ public function comments() { return $this->hasMany(Comment::class); } }
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 theComment
model ispost_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:use App\Models\Post; $comments = Post::find(1)->comments; foreach ($comments as $comment) { // }
Since all relationships also serve as query builders, you may add further constraints to the relationship query by calling the
comments
method and continuing to chain conditions onto the query:$comment = Post::find(1)->comments() ->where('title', 'foo') ->first();
Like the
hasOne
method, you may also override the foreign and local keys by passing additional arguments to thehasMany
method:return $this->hasMany(Comment::class, 'foreign_key'); return $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 thebelongsTo
method:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Comment extends Model { /** * Get the post that owns the comment. */ public function post() { return $this->belongsTo(Post::class); } }
Once the relationship has been defined, we can retrieve a comment's parent post by accessing the
post
"dynamic relationship property":use App\Models\Comment; $comment = Comment::find(1); return $comment->post->title;
In the example above, Eloquent will attempt to find a
Post
model that has anid
which matches thepost_id
column on theComment
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 thePost
model's foreign key on thecomments
table ispost_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:/** * Get the post that owns the comment. */ public function post() { return $this->belongsTo(Post::class, 'foreign_key'); }
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 thebelongsTo
method specifying your parent table's custom key:/** * Get the post that owns the comment. */ public function post() { return $this->belongsTo(Post::class, 'foreign_key', 'owner_key'); }
Default Models
The
belongsTo
,hasOne
,hasOneThrough
, andmorphOne
relationships allow you to define a default model that will be returned if the given relationship isnull
. This pattern is often referred to as the Null Object pattern and can help remove conditional checks in your code. In the following example, theuser
relation will return an emptyApp\Models\User
model if no user is attached to thePost
model:/** * Get the author of the post. */ public function user() { return $this->belongsTo(User::class)->withDefault(); }
To populate the default model with attributes, you may pass an array or closure to the
withDefault
method:/** * Get the author of the post. */ public function user() { return $this->belongsTo(User::class)->withDefault([ 'name' => 'Guest Author', ]); } /** * Get the author of the post. */ public function user() { return $this->belongsTo(User::class)->withDefault(function ($user, $post) { $user->name = 'Guest Author'; }); }
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 oneCar
model, and eachCar
model may be associated with oneOwner
model. While the mechanic and the owner have no direct relationship within the database, the mechanic can access the owner through theCar
model. Let's look at the tables necessary to define this relationship:mechanics id - integer name - string cars id - integer model - string mechanic_id - integer owners id - integer name - string car_id - integer
Now that we have examined the table structure for the relationship, let's define the relationship on the
Mechanic
model:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Mechanic extends Model { /** * Get the car's owner. */ public function carOwner() { return $this->hasOneThrough(Owner::class, Car::class); } }
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:class Mechanic extends Model { /** * Get the car's owner. */ public function carOwner() { return $this->hasOneThrough( Owner::class, Car::class, 'mechanic_id', // Foreign key on the cars table... 'car_id', // Foreign key on the owners table... 'id', // Local key on the mechanics table... 'id' // Local key on the cars table... ); } }
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 manyDeployment
models through an intermediateEnvironment
model. Using this example, you could easily gather all deployments for a given environment. Let's look at the tables required to define this relationship:projects id - integer name - string environments id - integer project_id - integer name - string deployments id - integer environment_id - integer commit_hash - string
Now that we have examined the table structure for the relationship, let's define the relationship on the
Project
model:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Project extends Model { /** * Get all of the deployments for the project. */ public function deployments() { return $this->hasManyThrough(Deployment::class, Environment::class); } }
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 aproject_id
column, thehasManyThrough
relation provides access to a project's deployments via$project->deployments
. To retrieve these models, Eloquent inspects theproject_id
column on the intermediateEnvironment
model's table. After finding the relevant environment IDs, they are used to query theDeployment
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:class Project extends Model { public function deployments() { return $this->hasManyThrough( Deployment::class, Environment::class, 'project_id', // Foreign key on the environments table... 'environment_id', // Foreign key on the deployments table... 'id', // Local key on the projects table... 'id' // Local key on the environments table... ); } }
Many To Many Relationships
Many-to-many relations are slightly more complicated than
hasOne
andhasMany
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
, androle_user
. Therole_user
table is derived from the alphabetical order of the related model names and containsuser_id
androle_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 theroles
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, therole_user
table is needed. We can summarize the relationship's table structure like so:users id - integer name - string roles id - integer name - string role_user user_id - integer role_id - integer
Model Structure
Many-to-many relationships are defined by writing a method that returns the result of the
belongsToMany
method. ThebelongsToMany
method is provided by theIlluminate\Database\Eloquent\Model
base class that is used by all of your application's Eloquent models. For example, let's define aroles
method on ourUser
model. The first argument passed to this method is the name of the related model class:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * The roles that belong to the user. */ public function roles() { return $this->belongsToMany(Role::class); } }
Once the relationship is defined, you may access the user's roles using the
roles
dynamic relationship property:use App\Models\User; $user = User::find(1); foreach ($user->roles as $role) { // }
Since all relationships also serve as query builders, you may add further constraints to the relationship query by calling the
roles
method and continuing to chain conditions onto the query:$roles = User::find(1)->roles()->orderBy('name')->get();
To determine the table name of the relationship's intermediate table, Eloquent will join the two related model names in alphabetical order. However, you are free to override this convention. You may do so by passing a second argument to the
belongsToMany
method:return $this->belongsToMany(Role::class, 'role_user');
In addition to customizing the name of the intermediate table, you may also customize the column names of the keys on the table by passing additional arguments to the
belongsToMany
method. The third argument is the foreign key name of the model on which you are defining the relationship, while the fourth argument is the foreign key name of the model that you are joining to:return $this->belongsToMany(Role::class, 'role_user', 'user_id', 'role_id');
Defining The Inverse Of The Relationship
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 theusers
method on theRole
model:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Role extends Model { /** * The users that belong to the role. */ public function users() { return $this->belongsToMany(User::class); } }
As you can see, the relationship is defined exactly the same as its
User
model counterpart with the exception of referencing theApp\Models\User
model. Since we're reusing thebelongsToMany
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 manyRole
models that it is related to. After accessing this relationship, we may access the intermediate table using thepivot
attribute on the models:use App\Models\User; $user = User::find(1); foreach ($user->roles as $role) { echo $role->pivot->created_at; }
Notice that each
Role
model we retrieve is automatically assigned apivot
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:return $this->belongsToMany(Role::class)->withPivot('active', 'created_by');
If you would like your intermediate table to have
created_at
andupdated_at
timestamps that are automatically maintained by Eloquent, call thewithTimestamps
method when defining the relationship:return $this->belongsToMany(Role::class)->withTimestamps();
{note} Intermediate tables that utilize Eloquent's automatically maintained timestamps are required to have both
created_at
andupdated_at
timestamp columns.Customizing The
pivot
Attribute NameAs 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 ofpivot
. This can be done using theas
method when defining the relationship:return $this->belongsToMany(Podcast::class) ->as('subscription') ->withTimestamps();
Once the custom intermediate table attribute has been specified, you may access the intermediate table data using the customized name:
$users = User::with('podcasts')->get(); foreach ($users->flatMap->podcasts as $podcast) { echo $podcast->subscription->created_at; }
Filtering Queries Via Intermediate Table Columns
You can also filter the results returned by
belongsToMany
relationship queries using thewherePivot
,wherePivotIn
, andwherePivotNotIn
methods when defining the relationship:return $this->belongsToMany(Role::class) ->wherePivot('approved', 1); return $this->belongsToMany(Role::class) ->wherePivotIn('priority', [1, 2]); return $this->belongsToMany(Role::class) ->wherePivotNotIn('priority', [1, 2]);
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 theIlluminate\Database\Eloquent\Relations\MorphPivot
class. For example, we may define aRole
model which uses a customRoleUser
pivot model:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Role extends Model { /** * The users that belong to the role. */ public function users() { return $this->belongsToMany(User::class)->using(RoleUser::class); } }
When defining the
RoleUser
model, you should extend theIlluminate\Database\Eloquent\Relations\Pivot
class:<?php namespace App\Models; use Illuminate\Database\Eloquent\Relations\Pivot; class RoleUser extends Pivot { // }
{note} Pivot models may not use the
SoftDeletes
trait. If you need to soft delete pivot records consider converting your pivot model to an actual Eloquent model.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 totrue
./** * Indicates if the IDs are auto-incrementing. * * @var bool */ public $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. a
Comment
model might belong to both thePost
andVideo
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 aUser
may share a polymorphic relation to anImage
model. Using a one-to-one polymorphic relation allows you to have a single table of unique images that may be associated with posts and users. First, let's examine the table structure:posts id - integer name - string users id - integer name - string images id - integer url - string imageable_id - integer imageable_type - string
Note the
imageable_id
andimageable_type
columns on theimages
table. Theimageable_id
column will contain the ID value of the post or user, while theimageable_type
column will contain the class name of the parent model. Theimageable_type
column is used by Eloquent to determine which "type" of parent model to return when accessing theimageable
relation. In this case, the column would contain eitherApp\Models\Post
orApp\Models\User
.Model Structure
Next, let's examine the model definitions needed to build this relationship:
<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Image extends Model { /** * Get the parent imageable model (user or post). */ public function imageable() { return $this->morphTo(); } } class Post extends Model { /** * Get the post's image. */ public function image() { return $this->morphOne(Image::class, 'imageable'); } } class User extends Model { /** * Get the user's image. */ public function image() { return $this->morphOne(Image::class, 'imageable'); } }
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:use App\Models\Post; $post = Post::find(1); $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 theimageable
method on theImage
model. So, we will access that method as a dynamic relationship property:use App\Models\Image; $image = Image::find(1); $imageable = $image->imageable;
The
imageable
relation on theImage
model will return either aPost
orUser
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:/** * Get the model that the image belongs to. */ public function imageable() { return $this->morphTo(__FUNCTION__, 'imageable_type', 'imageable_id'); }
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:posts id - integer title - string body - text videos id - integer title - string url - string comments id - integer body - text commentable_id - integer commentable_type - string
Model Structure
Next, let's examine the model definitions needed to build this relationship:
<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Comment extends Model { /** * Get the parent commentable model (post or video). */ public function commentable() { return $this->morphTo(); } } class Post extends Model { /** * Get all of the post's comments. */ public function comments() { return $this->morphMany(Comment::class, 'commentable'); } } class Video extends Model { /** * Get all of the video's comments. */ public function comments() { return $this->morphMany(Comment::class, 'commentable'); } }
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:use App\Models\Post; $post = Post::find(1); foreach ($post->comments as $comment) { // }
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 thecommentable
method on theComment
model. So, we will access that method as a dynamic relationship property in order to access the comment's parent model:use App\Models\Comment; $comment = Comment::find(1); $commentable = $comment->commentable;
The
commentable
relation on theComment
model will return either aPost
orVideo
instance, depending on which type of model is the comment's parent.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 andVideo
model could share a polymorphic relation to aTag
model. Using a many-to-many polymorphic relation in this situation would allow your application to have a single table of unique tags that may be associated with posts or videos. First, let's examine the table structure required to build this relationship:posts id - integer name - string videos id - integer name - string tags id - integer name - string taggables tag_id - integer taggable_id - integer taggable_type - string
{tip} Before diving into polymorphic many-to-many relationships, you may benefit from reading the documentation on typical many-to-many relationships.
Model Structure
Next, we're ready to define the relationships on the models. The
Post
andVideo
models will both contain atags
method that calls themorphToMany
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":<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Post extends Model { /** * Get all of the tags for the post. */ public function tags() { return $this->morphToMany(Tag::class, 'taggable'); } }
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 aposts
method and avideos
method. Both of these methods should return the result of themorphedByMany
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":<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Tag extends Model { /** * Get all of the posts that are assigned this tag. */ public function posts() { return $this->morphedByMany(Post::class, 'taggable'); } /** * Get all of the videos that are assigned this tag. */ public function videos() { return $this->morphedByMany(Video::class, 'taggable'); } }
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:use App\Models\Post; $post = Post::find(1); foreach ($post->tags as $tag) { // }
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 theposts
orvideos
methods on theTag
model:use App\Models\Tag; $tag = Tag::find(1); foreach ($tag->posts as $post) { // } foreach ($tag->videos as $video) { // }
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 aPost
or aVideo
model, the defaultcommentable_type
would be eitherApp\Models\Post
orApp\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
andvideo
. By doing so, the polymorphic "type" column values in our database will remain valid even if the models are renamed:use Illuminate\Database\Eloquent\Relations\Relation; Relation::morphMap([ 'post' => 'App\Models\Post', 'video' => 'App\Models\Video', ]);
You may register the
morphMap
in theboot
function of yourApp\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 theRelation::getMorphedModel
method:use Illuminate\Database\Eloquent\Relations\Relation; $alias = $post->getMorphClass(); $class = Relation::getMorphedModel($alias);
{note} When adding a "morph map" to your existing application, every morphable
*_type
column value in your database that still contains a fully-qualified class will need to be converted to its "map" name.Dynamic Relationships
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
resolveRelationshipUsing
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:use App\Models\Order; use App\Models\Customer; Order::resolveRelationUsing('customer', function ($orderModel) { return $orderModel->belongsTo(Customer::class, 'customer_id'); });
{note} When defining dynamic relationships, always provide explicit key name arguments to the Eloquent relationship methods.
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 associatedPost
models:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class User extends Model { /** * Get all of the posts for the user. */ public function posts() { return $this->hasMany(Post::class); } }
You may query the
posts
relationship and add additional constraints to the relationship like so:use App\Models\User; $user = User::find(1); $user->posts()->where('active', 1)->get();
You are able to use any of the Laravel query builder's 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.
Chaining
orWhere
Clauses After RelationshipsAs demonstrated in the example above, you are free to add additional constraints to relationships when querying them. However, use caution when chaining
orWhere
clauses onto a relationship, as theorWhere
clauses will be logically grouped at the same level as the relationship constraint:$user->posts() ->where('active', 1) ->orWhere('votes', '>=', 100) ->get();
The example above will generate the following SQL. As you can see, the
or
clause instructs the query to return any user with greater than 100 votes. The query is no longer constrained to a specific user:select * from posts where user_id = ? and active = 1 or votes >= 100
In most situations, you should use logical groups to group the conditional checks between parentheses:
use Illuminate\Database\Eloquent\Builder; $user->posts() ->where(function (Builder $query) { return $query->where('active', 1) ->orWhere('votes', '>=', 100); }) ->get();
The example above will produce the following SQL. Note that the logical grouping has properly grouped the constraints and the query remains constrained to a specific user:
select * from posts where user_id = ? and (active = 1 or votes >= 100)
Relationship Methods Vs. Dynamic Properties
If you do not need to add additional constraints to an Eloquent relationship query, you may access the relationship as if it were a property. For example, continuing to use our
User
andPost
example models, we may access all of a user's posts like so:use App\Models\User; $user = User::find(1); foreach ($user->posts as $post) { // }
Dynamic relationship properties perform "lazy loading", meaning they will only load their relationship data when you actually access them. Because of this, developers often use eager loading to pre-load relationships they know will be accessed after loading the model. Eager loading provides a significant reduction in SQL queries that must be executed to load a model's relations.
Querying Relationship Existence
When retrieving model records, you may wish to limit your results based on the existence of a relationship. For example, imagine you want to retrieve all blog posts that have at least one comment. To do so, you may pass the name of the relationship to the
has
andorHas
methods:use App\Models\Post; // Retrieve all posts that have at least one comment... $posts = Post::has('comments')->get();
You may also specify an operator and count value to further customize the query:
// Retrieve all posts that have three or more comments... $posts = Post::has('comments', '>=', 3)->get();
Nested
has
statements may be constructed using "dot" notation. For example, you may retrieve all posts that have at least one comment that has at least one image:// Retrieve posts that have at least one comment with images... $posts = Post::has('comments.images')->get();
If you need even more power, you may use the
whereHas
andorWhereHas
methods to define additional query constraints on yourhas
queries, such as inspecting the content of a comment:use Illuminate\Database\Eloquent\Builder; // Retrieve posts with at least one comment containing words like code%... $posts = Post::whereHas('comments', function (Builder $query) { $query->where('content', 'like', 'code%'); })->get(); // Retrieve posts with at least ten comments containing words like code%... $posts = Post::whereHas('comments', function (Builder $query) { $query->where('content', 'like', 'code%'); }, '>=', 10)->get();
{note} Eloquent does not currently support querying for relationship existence across databases. The relationships must exist within the same database.
Querying Relationship Absence
When retrieving model records, you may wish to limit your results based on the absence of a relationship. For example, imagine you want to retrieve all blog posts that don't have any comments. To do so, you may pass the name of the relationship to the
doesntHave
andorDoesntHave
methods:use App\Models\Post; $posts = Post::doesntHave('comments')->get();
If you need even more power, you may use the
whereDoesntHave
andorWhereDoesntHave
methods to add additional query constraints to yourdoesntHave
queries, such as inspecting the content of a comment:use Illuminate\Database\Eloquent\Builder; $posts = Post::whereDoesntHave('comments', function (Builder $query) { $query->where('content', 'like', 'code%'); })->get();
You may use "dot" notation to execute a query against a nested relationship. For example, the following query will retrieve all posts that do not have comments; however, posts that have comments from authors that are not banned will be included in the results:
use Illuminate\Database\Eloquent\Builder; $posts = Post::whereDoesntHave('comments.author', function (Builder $query) { $query->where('banned', 0); })->get();
Querying Morph To Relationships
To query the existence of "morph to" relationships, you may use the
whereHasMorph
andwhereDoesntHaveMorph
methods. These methods accept the name of the relationship as their first argument. Next, the methods accept the names of the related models that you wish to include in the query. Finally, you may provide a closure which customizes the relationship query:use App\Models\Comment; use App\Models\Post; use App\Models\Video; use Illuminate\Database\Eloquent\Builder; // Retrieve comments associated to posts or videos with a title like code%... $comments = Comment::whereHasMorph( 'commentable', [Post::class, Video::class], function (Builder $query) { $query->where('title', 'like', 'code%'); } )->get(); // Retrieve comments associated to posts with a title not like code%... $comments = Comment::whereDoesntHaveMorph( 'commentable', Post::class, function (Builder $query) { $query->where('title', 'like', 'code%'); } )->get();
You may occasionally need to add query constraints based on the "type" of the related polymorphic model. The closure passed to the
whereHasMorph
method may receive a$type
value as its second argument. This argument allows you to inspect the "type" of the query that is being built:use Illuminate\Database\Eloquent\Builder; $comments = Comment::whereHasMorph( 'commentable', [Post::class, Video::class], function (Builder $query, $type) { $column = $type === Post::class ? 'content' : 'title'; $query->where($column, 'like', 'code%'); } )->get();
Querying All Related Models
Instead of passing an array of possible polymorphic models, you may provide
*
as a wildcard value. This will instruct Laravel to retrieve all of the possible polymorphic types from the database. Laravel will execute an additional query in order to perform this operation:use Illuminate\Database\Eloquent\Builder; $comments = Comment::whereHasMorph('commentable', '*', function (Builder $query) { $query->where('title', 'like', 'foo%'); })->get();
Aggregating Related Models
Counting Related Models
Sometimes you may want to count the number of related models for a given relationship without actually loading the models. To accomplish this, you may use the
withCount
method. ThewithCount
method which will place a{relation}_count
attribute on the resulting models:use App\Models\Post; $posts = Post::withCount('comments')->get(); foreach ($posts as $post) { echo $post->comments_count; }
By passing an array to the
withCount
method, you may add the "counts" for multiple relations as well as add additional constraints to the queries:use Illuminate\Database\Eloquent\Builder; $posts = Post::withCount(['votes', 'comments' => function (Builder $query) { $query->where('content', 'like', 'code%'); }])->get(); echo $posts[0]->votes_count; echo $posts[0]->comments_count;
You may also alias the relationship count result, allowing multiple counts on the same relationship:
use Illuminate\Database\Eloquent\Builder; $posts = Post::withCount([ 'comments', 'comments as pending_comments_count' => function (Builder $query) { $query->where('approved', false); }, ])->get(); echo $posts[0]->comments_count; echo $posts[0]->pending_comments_count;
Deferred Count Loading
Using the
loadCount
method, you may load a relationship count after the parent model has already been retrieved:$book = Book::first(); $book->loadCount('genres');
If you need to set additional query constraints on the count query, you may pass an array keyed by the relationships you wish to count. The array values should be closures which receive the query builder instance:
$book->loadCount(['reviews' => function ($query) { $query->where('rating', 5); }])
Relationship Counting & Custom Select Statements
If you're combining
withCount
with aselect
statement, ensure that you callwithCount
after theselect
method:$posts = Post::select(['title', 'body']) ->withCount('comments') ->get();
Other Aggregate Functions
In addition to the
withCount
method, Eloquent provideswithMin
,withMax
,withAvg
, andwithSum
methods. These methods will place a{relation}_{function}_{column}
attribute on your resulting models:use App\Models\Post; $posts = Post::withSum('comments', 'votes')->get(); foreach ($posts as $post) { echo $post->comments_sum_votes; }
Like the
loadCount
method, deferred versions of these methods are also available. These additional aggregate operations may be performed on Eloquent models that have already been retrieved:$post = Post::first(); $post->loadSum('comments', 'votes');
Counting Related Models On Morph To Relationships
If you would like to eager load a "morph to" relationship, as well as related model counts for the various entities that may be returned by that relationship, you may utilize the
with
method in combination with themorphTo
relationship'smorphWithCount
method.In this example, let's assume that
Photo
andPost
models may createActivityFeed
models. We will assume theActivityFeed
model defines a "morph to" relationship namedparentable
that allows us to retrieve the parentPhoto
orPost
model for a givenActivityFeed
instance. Additionally, let's assume thatPhoto
models "have many"Tag
models andPost
models "have many"Comment
models.Now, let's imagine we want to retrieve
ActivityFeed
instances and eager load theparentable
parent models for eachActivityFeed
instance. In addition, we want to retrieve the number of tags that are associated with each parent photo and the number of comments that are associated with each parent post:use Illuminate\Database\Eloquent\Relations\MorphTo; $activities = ActivityFeed::with([ 'parentable' => function (MorphTo $morphTo) { $morphTo->morphWithCount([ Photo::class => ['tags'], Post::class => ['comments'], ]); }])->get();
Deferred Count Loading
Let's assume we have already retrieved a set of
ActivityFeed
models and now we would like to load the nested relationship counts for the variousparentable
models associated with the activity feeds. You may use theloadMorphCount
method to accomplish this:$activities = ActivityFeed::with('parentable')->get(); $activities->loadMorphCount('parentable', [ Photo::class => ['tags'], Post::class => ['comments'], ]);
Eager Loading
When accessing Eloquent relationships as properties, the related models are "lazy loaded". This means the relationship data is not actually loaded until you first access the property. However, Eloquent can "eager load" relationships at the time you query the parent model. Eager loading alleviates the "N + 1" query problem. To illustrate the N + 1 query problem, consider a
Book
model that "belongs to" to anAuthor
model:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Book extends Model { /** * Get the author that wrote the book. */ public function author() { return $this->belongsTo(Author::class); } }
Now, let's retrieve all books and their authors:
use App\Models\Book; $books = Book::all(); foreach ($books as $book) { echo $book->author->name; }
This loop will execute one query to retrieve all of the books within the database table, then another query for each book in order to retrieve the book's author. So, if we have 25 books, the code above would run 26 queries: one for the original book, and 25 additional queries to retrieve the author of each book.
Thankfully, we can use eager loading to reduce this operation to just two queries. When building a query, you may specify which relationships should be eager loaded using the
with
method:$books = Book::with('author')->get(); foreach ($books as $book) { echo $book->author->name; }
For this operation, only two queries will be executed - one query to retrieve all of the books and one query to retrieve all of the authors for all of the books:
select * from books select * from authors where id in (1, 2, 3, 4, 5, ...)
Eager Loading Multiple Relationships
Sometimes you may need to eager load several different relationships. To do so, just pass an array of relationships to the
with
method:$books = Book::with(['author', 'publisher'])->get();
Nested Eager Loading
To eager a relationship's relationships, you may use "dot" syntax. For example, let's eager load all of the book's authors and all of the author's personal contacts:
$books = Book::with('author.contacts')->get();
Nested Eager Loading
morphTo
RelationshipsIf you would like to eager load a
morphTo
relationship, as well as nested relationships on the various entities that may be returned by that relationship, you may use thewith
method in combination with themorphTo
relationship'smorphWith
method. To help illustrate this method, let's consider the following model:<?php use Illuminate\Database\Eloquent\Model; class ActivityFeed extends Model { /** * Get the parent of the activity feed record. */ public function parentable() { return $this->morphTo(); } }
In this example, let's assume
Event
,Photo
, andPost
models may createActivityFeed
models. Additionally, let's assume thatEvent
models belong to aCalendar
model,Photo
models are associated withTag
models, andPost
models belong to anAuthor
model.Using these model definitions and relationships, we may retrieve
ActivityFeed
model instances and eager load allparentable
models and their respective nested relationships:use Illuminate\Database\Eloquent\Relations\MorphTo; $activities = ActivityFeed::query() ->with(['parentable' => function (MorphTo $morphTo) { $morphTo->morphWith([ Event::class => ['calendar'], Photo::class => ['tags'], Post::class => ['author'], ]); }])->get();
Eager Loading Specific Columns
You may not always need every column from the relationships you are retrieving. For this reason, Eloquent allows you to specify which columns of the relationship you would like to retrieve:
$books = Book::with('author:id,name')->get();
{note} When using this feature, you should always include the
id
column and any relevant foreign key columns in the list of columns you wish to retrieve.Eager Loading By Default
Sometimes you might want to always load some relationships when retrieving a model. To accomplish this, you may define a
$with
property on the model:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Book extends Model { /** * The relationships that should always be loaded. * * @var array */ protected $with = ['author']; /** * Get the author that wrote the book. */ public function author() { return $this->belongsTo(Author::class); } }
If you would like to remove an item from the
$with
property for a single query, you may use thewithout
method:$books = Book::without('author')->get();
Constraining Eager Loads
Sometimes you may wish to eager load a relationship but also specify additional query conditions for the eager loading query. You can accomplish this by passing an array of relationships to the
with
method where the array key is a relationship name and the array value is a closure that adds additional constraints to the eager loading query:use App\Models\User; $users = User::with(['posts' => function ($query) { $query->where('title', 'like', '%code%'); }])->get();
In this example, Eloquent will only eager load posts where the post's
title
column contains the wordcode
. You may call other query builder methods to further customize the eager loading operation:$users = User::with(['posts' => function ($query) { $query->orderBy('created_at', 'desc'); }])->get();
{note} The
limit
andtake
query builder methods may not be used when constraining eager loads.Constraining Eager Loading Of
morphTo
RelationshipsIf you are eager loading a
morphTo
relationship, Eloquent will run multiple queries to fetch each type of related model. You may add additional constraints to each of these queries using theMorphTo
relation'sconstrain
method:use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\Relations\MorphTo; $comments = Comment::with(['commentable' => function (MorphTo $morphTo) { $morphTo->constrain([ Post::class => function (Builder $query) { $query->whereNull('hidden_at'); }, Video::class => function (Builder $query) { $query->where('type', 'educational'); }, ]); }])->get();
In this example, Eloquent will only eager load posts that have not been hidden and videos have a
type
value of "educational".Lazy Eager Loading
Sometimes you may need to eager load a relationship after the parent model has already been retrieved. For example, this may be useful if you need to dynamically decide whether to load related models:
use App\Models\Book; $books = Book::all(); if ($someCondition) { $books->load('author', 'publisher'); }
If you need to set additional query constraints on the eager loading query, you may pass an array keyed by the relationships you wish to load. The array values should be closure instances which receive the query instance:
$author->load(['books' => function ($query) { $query->orderBy('published_date', 'asc'); }]);
To load a relationship only when it has not already been loaded, use the
loadMissing
method:$book->loadMissing('author');
Nested Lazy Eager Loading &
morphTo
If you would like to eager load a
morphTo
relationship, as well as nested relationships on the various entities that may be returned by that relationship, you may use theloadMorph
method.This method accepts the name of the
morphTo
relationship as its first argument, and an array of model / relationship pairs as its second argument. To help illustrate this method, let's consider the following model:<?php use Illuminate\Database\Eloquent\Model; class ActivityFeed extends Model { /** * Get the parent of the activity feed record. */ public function parentable() { return $this->morphTo(); } }
In this example, let's assume
Event
,Photo
, andPost
models may createActivityFeed
models. Additionally, let's assume thatEvent
models belong to aCalendar
model,Photo
models are associated withTag
models, andPost
models belong to anAuthor
model.Using these model definitions and relationships, we may retrieve
ActivityFeed
model instances and eager load allparentable
models and their respective nested relationships:$activities = ActivityFeed::with('parentable') ->get() ->loadMorph('parentable', [ Event::class => ['calendar'], Photo::class => ['tags'], Post::class => ['author'], ]);
Inserting & Updating Related Models
The
save
MethodEloquent provides convenient methods for adding new models to relationships. For example, perhaps you need to add a new comment to a post. Instead of manually setting the
post_id
attribute on theComment
model you may insert the comment using the relationship'ssave
method:use App\Models\Comment; use App\Models\Post; $comment = new Comment(['message' => 'A new comment.']); $post = Post::find(1); $post->comments()->save($comment);
Note that we did not access the
comments
relationship as a dynamic property. Instead, we called thecomments
method to obtain an instance of the relationship. Thesave
method will automatically add the appropriatepost_id
value to the newComment
model.If you need to save multiple related models, you may use the
saveMany
method:$post = Post::find(1); $post->comments()->saveMany([ new Comment(['message' => 'A new comment.']), new Comment(['message' => 'Another new comment.']), ]);
The
save
andsaveMany
methods will not add the new models to any in-memory relationships that are already loaded onto the parent model. If you plan on accessing the relationship after using thesave
orsaveMany
methods, you may wish to use therefresh
method to reload the model and its relationships:$post->comments()->save($comment); $post->refresh(); // All comments, including the newly saved comment... $post->comments;
Recursively Saving Models & Relationships
If you would like to
save
your model and all of its associated relationships, you may use thepush
method. In this example, thePost
model will be saved as well as its comments and the comment's authors:$post = Post::find(1); $post->comments[0]->message = 'Message'; $post->comments[0]->author->name = 'Author Name'; $post->push();
The
create
MethodIn addition to the
save
andsaveMany
methods, you may also use thecreate
method, which accepts an array of attributes, creates a model, and inserts it into the database. The difference betweensave
andcreate
is thatsave
accepts a full Eloquent model instance whilecreate
accepts a plain PHParray
. The newly created model will be returned by thecreate
method:use App\Models\Post; $post = Post::find(1); $comment = $post->comments()->create([ 'message' => 'A new comment.', ]);
You may use the
createMany
method to create multiple related models:$post = Post::find(1); $post->comments()->createMany([ ['message' => 'A new comment.'], ['message' => 'Another new comment.'], ]);
You may also use the
findOrNew
,firstOrNew
,firstOrCreate
, andupdateOrCreate
methods to create and update models on relationships.{tip} Before using the
create
method, be sure to review the mass assignment documentation.Belongs To Relationships
If you would like to assign a child model to a new parent model, you may use the
associate
method. In this example, theUser
model defines abelongsTo
relationship to theAccount
model. Thisassociate
method will set the foreign key on the child model:use App\Models\Account; $account = Account::find(10); $user->account()->associate($account); $user->save();
To remove a parent model from a child model, you may use the
dissociate
method. This method will set the relationship's foreign key tonull
:$user->account()->dissociate(); $user->save();
Many To Many Relationships
Attaching / Detaching
Eloquent also provides methods to make working with many-to-many relationships more convenient. For example, let's imagine a user can have many roles and a role can have many users. You may use the
attach
method to attach a role to a user by inserting a record in the relationship's intermediate table:use App\Models\User; $user = User::find(1); $user->roles()->attach($roleId);
When attaching a relationship to a model, you may also pass an array of additional data to be inserted into the intermediate table:
$user->roles()->attach($roleId, ['expires' => $expires]);
Sometimes it may be necessary to remove a role from a user. To remove a many-to-many relationship record, use the
detach
method. Thedetach
method will delete the appropriate record out of the intermediate table; however, both models will remain in the database:// Detach a single role from the user... $user->roles()->detach($roleId); // Detach all roles from the user... $user->roles()->detach();
For convenience,
attach
anddetach
also accept arrays of IDs as input:$user = User::find(1); $user->roles()->detach([1, 2, 3]); $user->roles()->attach([ 1 => ['expires' => $expires], 2 => ['expires' => $expires], ]);
Syncing Associations
You may also use the
sync
method to construct many-to-many associations. Thesync
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]);
You may also pass additional intermediate table values with the IDs:
$user->roles()->sync([1 => ['expires' => true], 2, 3]);
If you do not want to detach existing IDs that are missing from the given array, you may use the
syncWithoutDetaching
method:$user->roles()->syncWithoutDetaching([1, 2, 3]);
Toggling Associations
The many-to-many relationship also provides a
toggle
method which "toggles" the attachment status of the given related model IDs. If the given ID is currently attached, it will be detached. Likewise, if it is currently detached, it will be attached:$user->roles()->toggle([1, 2, 3]);
Updating A Record On The Intermediate Table
If you need to update an existing row in your relationship's intermediate table, you may use the
updateExistingPivot
method. This method accepts the intermediate record foreign key and an array of attributes to update:$user = User::find(1); $user->roles()->updateExistingPivot($roleId, [ 'active' => false, ]);
Touching Parent Timestamps
When a model defines a
belongsTo
orbelongsToMany
relationship to another model, such as aComment
which belongs to aPost
, 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" theupdated_at
timestamp of the owningPost
so that it is set to the current date and time. To accomplish this, you may add atouches
property to your child model containing the names of the relationships that should have theirupdated_at
timestamps updated when the child model is updated:<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; class Comment extends Model { /** * All of the relationships to be touched. * * @var array */ protected $touches = ['post']; /** * Get the post that the comment belongs to. */ public function post() { return $this->belongsTo(Post::class); } }
{note} Parent model timestamps will only be updated if the child model is updated using Eloquent's
save
method.