Custom pivot-modellen en chaperone

Wat is een custom pivot-model?

De tussentabel van belongsToMany (veel-op-veel) wordt standaard behandeld als een kale Illuminate\Database\Eloquent\Relations\Pivot-instantie. Wil je extra kolommen op de tussentabel bijhouden (goedkeuringsdatum, roltype, enzovoort) of accessors, mutators of eigen methoden toevoegen, maak dan een custom model dat overerft van Pivot.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\Pivot;

class RoleUser extends Pivot
{
    protected function casts(): array
    {
        return [
            'approved' => 'boolean',
        ];
    }
}

Roep in de belongsToMany-definitie de methode using() aan om de relatie te vertellen dat dit custom model gebruikt moet worden.

<?php

namespace App\Models;

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

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

Noem custom pivot-modellen altijd volgens de conventie alfabetisch gesorteerd en in het enkelvoud (RoleUser, niet UserRole). Dit is echter alleen een naamgevingsconventie; technisch mag je elke klassenaam gebruiken.

Attributen kiezen met `as()`

Standaard benader je waarden uit de tussentabel via de property pivot. Met de methode as() kun je deze naam wijzigen.

return $this->belongsToMany(Role::class)
    ->using(RoleUser::class)
    ->as('membership')
    ->withTimestamps()
    ->withPivot('approved');

foreach ($user->roles as $role) {
    echo $role->membership->approved;
    echo $role->membership->created_at;
}

Extra kolommen en timestamps

Als je tussentabel extra kolommen zoals approved heeft, geef je die expliciet aan met withPivot(). Wil je created_at / updated_at beheren, gebruik dan withTimestamps().

return $this->belongsToMany(Role::class)
    ->using(RoleUser::class)
    ->withPivot('approved')
    ->withTimestamps();

Eloquent werkt de updated_at van de tussentabel alleen automatisch bij als het pivot-model expliciet via using() is opgegeven. withTimestamps() werkt ook met de standaard Pivot-klasse, maar door met using() een custom model op te geven kun je gebruikmaken van custom events, custom casts en meer.

Terugverwijzen vanuit het pivot-model

Op een custom pivot-model kun je vrijelijk belongsTo-relaties definiëren naar het bronmodel en het gerelateerde model.

<?php

namespace App\Models;

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

class RoleUser extends Pivot
{
    public function role(): BelongsTo
    {
        return $this->belongsTo(Role::class);
    }

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

Zo kun je, ook als je alleen het pivot-model zelf ophaalt, via $roleUser->role of $roleUser->user bij de gerelateerde modellen komen. Wil je deze relaties automatisch eager laden wanneer de parent-query wordt uitgevoerd, dan biedt de hieronder beschreven chaperone() een oplossing.

Automatische eager loading met `chaperone()` (Laravel 13)

Laravel 13 heeft de methode chaperone() toegevoegd. Daarmee kun je belongsTo-relaties zoals role() / user() die op het pivot-model zijn gedefinieerd, automatisch laten hydraten (het equivalent van eager loading) wanneer een belongsToMany-query wordt uitgevoerd.

<?php

namespace App\Models;

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

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

Wanneer je chaperone() aanroept, leidt Eloquent automatisch de namen af van de belongsTo-relaties op het pivot-model (RoleUser). Bij het ophalen van een collectie zoals Role::with('users') stelt het de verwijzingen naar het bronmodel en het gerelateerde model in op elke pivot, zonder extra queries uit te voeren.

$role = Role::with('users')->first();

foreach ($role->users as $user) {
    // Bereikbaar zonder extra queries, via de pivot naar het parent-model
    echo $user->pivot->role->name;
}

Niet-standaard relatienamen gebruiken

Wijken de methodenamen van de belongsTo-relaties op je pivot-model af van de standaardconventie (camelCase enkelvoud van het bron- en gerelateerde model), geef ze dan expliciet mee als argumenten van chaperone().

return $this->belongsToMany(User::class)
    ->using(RoleUser::class)
    ->chaperone(declaring: 'role', related: 'user');

chaperone() lost het “N+1-probleem” ook op voor verwijzingen die via de tussentabel lopen. In applicaties die vaak informatie van het parent-model via het pivot-model tonen (bijvoorbeeld goedkeuringsdatum samen met de gebruikersnaam) is deze methode bijzonder effectief in combinatie met de reguliere eager loading via with().

Volgende stappen

Relaties

Ga terug naar de basisdefinities van relaties, inclusief belongsToMany, om te herhalen.

Eloquent Observers en model events

Leer hoe je met model events het opslaan en bijwerken van pivot-modellen kunt hooken.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Wat is een custom pivot-model?

Attributen kiezen met `as()`

Extra kolommen en timestamps

Terugverwijzen vanuit het pivot-model

Automatische eager loading met `chaperone()` (Laravel 13)

Niet-standaard relatienamen gebruiken

Volgende stappen

Relaties

Eloquent Observers en model events

​Wat is een custom pivot-model?

​Attributen kiezen met as()

​Extra kolommen en timestamps

​Terugverwijzen vanuit het pivot-model

​Automatische eager loading met chaperone() (Laravel 13)

​Niet-standaard relatienamen gebruiken

​Volgende stappen

Relaties

Eloquent Observers en model events

Wat is een custom pivot-model?

Attributen kiezen met `as()`

Extra kolommen en timestamps

Terugverwijzen vanuit het pivot-model

Automatische eager loading met `chaperone()` (Laravel 13)

Niet-standaard relatienamen gebruiken

Volgende stappen