Eloquent relationships

Overview

Database tables are often related to one another. A blog post has many comments; an order belongs to a user. Eloquent makes it easy to define these relationships and query related data in a natural, expressive way. Relationships are defined as methods on your Eloquent model classes.

Examples on this page use User, Post, Comment, and Tag models. Assume these models and their database tables already exist.

The main relationship types Eloquent supports:

Relationship	Description
`hasOne`	One-to-one (parent owns one child)
`belongsTo`	Inverse of one-to-one or one-to-many
`hasMany`	One-to-many (parent owns many children)
`belongsToMany`	Many-to-many (via a pivot table)

hasOne (one-to-one)

Use hasOne when a model owns exactly one related model. For example, a User has one Profile.

Defining the relationship

<?php

namespace App\Models;

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

class User extends Model
{
    public function profile(): HasOne
    {
        return $this->hasOne(Profile::class);
    }
}

Eloquent assumes the profiles table has a user_id foreign key based on the parent model name. Access the relationship as a property — Eloquent queries the database automatically:

$user = User::find(1);
$profile = $user->profile;

Calling a relationship method as a property is called a “dynamic relationship property”. Eloquent runs the query and returns the result the first time you access it.

belongsTo (inverse of hasOne)

belongsTo is the inverse of hasOne. Define it on the model that holds the foreign key — in this case, Profile belongs to User.

<?php

namespace App\Models;

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

class Profile extends Model
{
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

Eloquent uses the method name plus _id as the foreign key (user_id).

$profile = Profile::find(1);
$user = $profile->user;

echo $user->name;

hasMany (one-to-many)

hasMany is the most common relationship type. Use it when a parent model owns multiple child models — for example, a Post has many Comment records.

Defining the relationship

<?php

namespace App\Models;

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

class Post extends Model
{
    public function comments(): HasMany
    {
        return $this->hasMany(Comment::class);
    }
}

Eloquent assumes the comments table has a post_id foreign key. A hasMany relationship returns a collection:

$post = Post::find(1);

foreach ($post->comments as $comment) {
    echo $comment->body;
}

Chain query constraints by calling the relationship as a method:

$recentComments = Post::find(1)
    ->comments()
    ->latest()
    ->take(5)
    ->get();

Inverse relationship

To navigate from a comment back to its post, define belongsTo on Comment:

<?php

namespace App\Models;

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

class Comment extends Model
{
    public function post(): BelongsTo
    {
        return $this->belongsTo(Post::class);
    }
}

$comment = Comment::find(1);
echo $comment->post->title;

Filtering with `whereBelongsTo()`

When retrieving the children of a belongsTo relationship, you could manually specify the foreign key with where('post_id', $post->id), but the whereBelongsTo method automatically determines the proper relationship and foreign key for the given model:

$comments = Comment::whereBelongsTo($post)->get();

You may also pass a collection instance. In that case, Laravel retrieves models that belong to any of the parent models within the collection:

$posts = Post::where('featured', true)->get();

$comments = Comment::whereBelongsTo($posts)->get();

By default the relationship is determined from the class name of the given model, but you may specify the relationship name explicitly as the second argument:

$comments = Comment::whereBelongsTo($post, 'post')->get();

Automatic parent hydration with `chaperone()`

Even after eager loading with Post::with('comments'), accessing $comment->post on each child triggers an additional query, leading to an N+1 problem. Adding chaperone() to the hasMany definition makes Eloquent automatically hydrate the parent model onto each child, avoiding this extra query.

<?php

namespace App\Models;

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

class Post extends Model
{
    public function comments(): HasMany
    {
        return $this->hasMany(Comment::class)->chaperone();
    }
}

If you’d rather enable this only at query time without changing the relationship definition, call chaperone() inside with():

$posts = Post::with([
    'comments' => fn ($comments) => $comments->chaperone(),
])->get();

chaperone() works the same way for polymorphic morphMany relationships. For chaperone() on belongsToMany pivot models, see Custom pivot models and chaperone.

belongsToMany (many-to-many)

Use a many-to-many relationship when both models can be associated with multiple instances of each other. For example, a Post can have many Tag records, and a Tag can belong to many posts.

Table structure

Many-to-many relationships require a pivot table. For Post and Tag, create a post_tag pivot table:

posts
    id - integer
    title - string

tags
    id - integer
    name - string

post_tag
    post_id - integer
    tag_id - integer

Eloquent infers the pivot table name by alphabetically combining the two model names: post + tag → post_tag.

Defining the relationship

<?php

namespace App\Models;

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

class Post extends Model
{
    public function tags(): BelongsToMany
    {
        return $this->belongsToMany(Tag::class);
    }
}

Define the inverse on Tag to navigate in both directions:

<?php

namespace App\Models;

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

class Tag extends Model
{
    public function posts(): BelongsToMany
    {
        return $this->belongsToMany(Post::class);
    }
}

$post = Post::find(1);

foreach ($post->tags as $tag) {
    echo $tag->name;
}

Attaching and detaching

Use attach() to add a record to the pivot table, detach() to remove one:

$post = Post::find(1);

// Add a tag
$post->tags()->attach($tagId);

// Remove a tag
$post->tags()->detach($tagId);

// Replace all current associations
$post->tags()->sync([$tagId1, $tagId2]);

sync() removes any pivot rows not included in the given array and inserts the ones that are missing, leaving you with exactly the specified set of associations.

For advanced usage — storing extra columns on the pivot table or specifying a custom pivot model with using() — see Custom pivot models and chaperone.

Eager loading

The N+1 problem

When you access a relationship as a property, Eloquent runs a separate query each time. Inside a loop this creates an N+1 problem:

// 1 query to retrieve all posts
$posts = Post::all();

foreach ($posts as $post) {
    // 1 additional query per post to retrieve its user
    echo $post->user->name;
}

With 100 posts, this runs 101 queries, which has a significant impact on performance.

Eager loading with `with()`

Use with() to load all related data in just two queries:

// 2 queries total regardless of the number of posts
$posts = Post::with('user')->get();

foreach ($posts as $post) {
    // No additional queries
    echo $post->user->name;
}

The two queries are:

select * from posts

select * from users where id in (1, 2, 3, ...)

Loading multiple relationships

Pass an array to eager-load several relationships at once:

$posts = Post::with(['user', 'comments', 'tags'])->get();

Nested eager loading

Use dot notation to eager-load nested relationships:

// Load each post's comments and each comment's user
$posts = Post::with('comments.user')->get();

Eager loading is essential for preventing performance problems. Make it a habit to use with() whenever you loop over models and access relationships.

Next steps

Authentication

Learn how to add login and registration to your Laravel application.

Getting Started

Basics

Request Handling

Database

Authentication

Helpers and External Communication

Testing and Deployment

AI Development Support

Overview

hasOne (one-to-one)

Defining the relationship

belongsTo (inverse of hasOne)

hasMany (one-to-many)

Defining the relationship

Inverse relationship

Filtering with `whereBelongsTo()`

Automatic parent hydration with `chaperone()`

belongsToMany (many-to-many)

Table structure

Defining the relationship

Attaching and detaching

Eager loading

The N+1 problem

Eager loading with `with()`

Loading multiple relationships

Nested eager loading

Next steps

Authentication

​Overview

​hasOne (one-to-one)

​Defining the relationship

​Accessing the related model

​belongsTo (inverse of hasOne)

​hasMany (one-to-many)

​Defining the relationship

​Accessing related records

​Inverse relationship

​Filtering with whereBelongsTo()

​Automatic parent hydration with chaperone()

​belongsToMany (many-to-many)

​Table structure

​Defining the relationship

​Retrieving related records

​Attaching and detaching

​Eager loading

​The N+1 problem

​Eager loading with with()

​Loading multiple relationships

​Nested eager loading

​Next steps

Authentication

Overview

hasOne (one-to-one)

Defining the relationship

Accessing the related model

belongsTo (inverse of hasOne)

hasMany (one-to-many)

Defining the relationship

Accessing related records

Inverse relationship

Filtering with `whereBelongsTo()`

Automatic parent hydration with `chaperone()`

belongsToMany (many-to-many)

Table structure

Defining the relationship

Retrieving related records

Attaching and detaching

Eager loading

The N+1 problem

Eager loading with `with()`

Loading multiple relationships

Nested eager loading

Next steps