> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eloquent relationships

> Define and query one-to-one, one-to-many, and many-to-many relationships between Eloquent models.

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

> [!NOTE]
>
> 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) |

```mermaid theme={null}
erDiagram
    users ||--o| profiles : "hasOne / belongsTo (profiles.user_id)"
    posts ||--o{ comments : "hasMany / belongsTo (comments.post_id)"
    posts }o--o{ tags : "belongsToMany (post_tag 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 theme={null}
<?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.

### Accessing the related model

Access the relationship as a property — Eloquent queries the database automatically:

```php theme={null}
$user = User::find(1);
$profile = $user->profile;
```

> [!TIP]
>
> 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 theme={null}
<?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`).

```php theme={null}
$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 theme={null}
<?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.

### Accessing related records

A `hasMany` relationship returns a collection:

```php theme={null}
$post = Post::find(1);

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

Chain query constraints by calling the relationship as a method:

```php theme={null}
$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 theme={null}
<?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);
    }
}
```

```php theme={null}
$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:

```php theme={null}
$comments = Comment::whereBelongsTo($post)->get();
```

You may also pass a [collection](https://kawax.biz/en/eloquent-collections.md) instance. In that case, Laravel retrieves models that belong to any of the parent models within the collection:

```php theme={null}
$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:

```php theme={null}
$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 theme={null}
<?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()`:

```php theme={null}
$posts = Post::with([
    'comments' => fn ($comments) => $comments->chaperone(),
])->get();
```

> [!NOTE]
>
> `chaperone()` works the same way for polymorphic `morphMany` relationships. For `chaperone()` on `belongsToMany` pivot models, see [Custom pivot models and chaperone](https://kawax.biz/en/advanced/eloquent-custom-pivot.md).

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

```text theme={null}
posts
    id - integer
    title - string

tags
    id - integer
    name - string

post_tag
    post_id - integer
    tag_id - integer
```

> [!NOTE]
>
> Eloquent infers the pivot table name by alphabetically combining the two model names: `post` + `tag` → `post_tag`.

### Defining the relationship

```php theme={null}
<?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 theme={null}
<?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);
    }
}
```

### Retrieving related records

```php theme={null}
$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:

```php theme={null}
$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]);
```

> [!TIP]
>
> `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.

> [!NOTE]
>
> For advanced usage — storing extra columns on the pivot table or specifying a custom pivot model with `using()` — see [Custom pivot models and chaperone](https://kawax.biz/en/advanced/eloquent-custom-pivot.md).

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

```php theme={null}
// 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:

```php theme={null}
// 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:

```sql theme={null}
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:

```php theme={null}
$posts = Post::with(['user', 'comments', 'tags'])->get();
```

### Nested eager loading

Use dot notation to eager-load nested relationships:

```php theme={null}
// Load each post's comments and each comment's user
$posts = Post::with('comments.user')->get();
```

> [!WARNING]
>
> 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

> [card] [Authentication](https://kawax.biz/en/authentication.md)
>
> Learn how to add login and registration to your Laravel application.

> [card] [Registering dynamic relationships in packages](https://kawax.biz/en/advanced/package-dynamic-relations.md)
>
> Learn how to add relationships from a distributed package without modifying models, and what to watch for with key definitions, name collisions, and inheritance.


## Related topics

- [Eloquent serialization](https://kawax.biz/en/eloquent-serialization.md)
- [Eloquent API resources](https://kawax.biz/en/eloquent-resources.md)
- [Registering dynamic relationships in packages](https://kawax.biz/en/advanced/package-dynamic-relations.md)
- [Laravel Scout](https://kawax.biz/en/scout.md)
- [Package morph maps and stored data compatibility](https://kawax.biz/en/advanced/package-morph-maps.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.