In Laravel, relationships between database tables are a fundamental part of building complex applications. One of the most common relationships is the many-to-many relationship, where multiple records in one table are associated with multiple records in another table. This is typically managed using an intermediate (pivot) table.

In this in-depth guide, we will explore how to:

• Set up a many-to-many relationship in Laravel
• Define relationships in Eloquent models
• Work with pivot tables
• Retrieve and manipulate related records
• Use additional pivot table attributes
• Perform eager loading for optimization

By the end of this tutorial, you will have a solid grasp of many-to-many relationships in Laravel and how to efficiently retrieve and manage data.

Understanding Many-to-Many Relationships

A many-to-many relationship exists when multiple records in one table are related to multiple records in another table. To implement this, we use a pivot table, which contains the foreign keys of the related tables.

For example, in a blog application:

• Users can belong to multiple Roles (Admin, Editor, User, etc.).
• Roles can have multiple Users.

To handle this, a pivot table (e.g., role_user) is used to link users and roles.

Setting Up the Database Schema

Step 1: Create Migration Files

First, create migration files for users, roles, and role_user tables.

Creating the Users Table

php artisan make:migration create_users_table

Modify database/migrations/YYYY_MM_DD_create_users_table.php:

 
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->unique();
    $table->string('password');
    $table->timestamps();
});
 

Creating the Roles Table

 php artisan make:migration create_roles_table
 

Modify database/migrations/YYYY_MM_DD_create_roles_table.php:

 Schema::create('roles', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});
 

Creating the Pivot Table

php artisan make:migration create_role_user_table

Modify database/migrations/YYYY_MM_DD_create_role_user_table.php:

 

Schema::create('role_user', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->foreignId('role_id')->constrained()->onDelete('cascade');
    $table->timestamps();
});
 

Run the migrations:

 php artisan migrate
 

Defining the Relationship in Eloquent Models

Now that we have our database tables, we need to define the many-to-many relationship in our models.

User Model (app/Models/User.php)

 use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function roles()
    {
        return $this->belongsToMany(Role::class);
    }
}

Role Model (app/Models/Role.php)

 use Illuminate\Database\Eloquent\Model;

class Role extends Model
{
    public function users()
    {
        return $this->belongsToMany(User::class);
    }
}

Working with Many-to-Many Relationships

Attaching and Detaching Roles to a User

Attaching Roles

$user = User::find(1);
$user->roles()->attach([1, 2]); // Assign roles with IDs 1 and 2 to the user
 

Detaching Roles

 $user->roles()->detach(1); // Remove role with ID 1 from the user

 

Syncing Roles

$user->roles()->sync([2, 3]); // Remove existing roles and assign new ones
 

Retrieving Data from the Pivot Table

By default, Laravel automatically retrieves data from the pivot table.

$user = User::find(1);
$roles = $user->roles; // Fetch all roles assigned to the user
 

Accessing Pivot Table Data

You can define additional fields in the pivot table (e.g., assigned_at) and access them using withPivot:

Modify the relationship:

public function roles()
{
    return $this->belongsToMany(Role::class)->withPivot('assigned_at');
}


Retrieve pivot data:

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

 

Eager Loading Many-to-Many Relationships

Eager loading reduces the number of queries by fetching related records upfront.

$users = User::with('roles')->get();
 

Querying Many-to-Many Relationships

Finding Users with a Specific Role

$admins = User::whereHas('roles', function ($query) {
    $query->where('name', 'Admin');
})->get();
 

Finding Roles for a Given User

$roles = Role::whereHas('users', function ($query) {
    $query->where('name', 'John Doe');
})->get();

 

Using Pivot Tables in API Responses

To include pivot table data in API responses:

return response()->json(User::with('roles')->get());
 

Best Practices for Many-to-Many Relationships

1. Use meaningful pivot table names (e.g., role_user, post_tag).
2. Use sync() instead of attach() for mass updates to prevent duplicates.
3. Utilize eager loading to reduce database queries.
4. Use withPivot() for additional pivot table attributes.
5. Apply whereHas() for filtering related records efficiently.

Conclusion

Many-to-many relationships are powerful when managing complex data associations. With Laravel’s Eloquent ORM, handling many-to-many relationships is intuitive and efficient. By leveraging pivot tables, eager loading, and querying techniques, you can optimize your database interactions and improve application performance.

Start implementing many-to-many relationships in your Laravel projects and explore ways to enhance them for better data handling!