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

# Custom pivot-modellen en chaperone

> Hoe je de tussentabel van belongsToMany behandelt als een custom Pivot-model, en hoe de in Laravel 13 toegevoegde chaperone zorgt voor automatische eager loading.

## Wat is een custom pivot-model?

De tussentabel van [belongsToMany (veel-op-veel)](/nl/eloquent-relationships#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 theme={null}
<?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 theme={null}
<?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);
    }
}
```

<Info>
  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.
</Info>

## Attributen kiezen met `as()`

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

```php theme={null}
return $this->belongsToMany(Role::class)
    ->using(RoleUser::class)
    ->as('membership')
    ->withTimestamps()
    ->withPivot('approved');
```

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

```php theme={null}
return $this->belongsToMany(Role::class)
    ->using(RoleUser::class)
    ->withPivot('approved')
    ->withTimestamps();
```

<Warning>
  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.
</Warning>

## 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 theme={null}
<?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 theme={null}
<?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.

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

```php theme={null}
return $this->belongsToMany(User::class)
    ->using(RoleUser::class)
    ->chaperone(declaring: 'role', related: 'user');
```

<Tip>
  `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()`.
</Tip>

## Volgende stappen

<Card title="Relaties" icon="link" href="/nl/eloquent-relationships">
  Ga terug naar de basisdefinities van relaties, inclusief belongsToMany, om te herhalen.
</Card>

<Card title="Eloquent Observers en model events" icon="bolt" href="/nl/advanced/eloquent-observers">
  Leer hoe je met model events het opslaan en bijwerken van pivot-modellen kunt hooken.
</Card>


## Related topics

- [Introductie tot Eloquent-relaties](/nl/eloquent-relationships.md)
- [Modellen](/nl/packages/laravel-copilot-sdk/models.md)
- [Custom casts van Eloquent](/nl/advanced/eloquent-casts.md)
- [Een custom provider voor de AI SDK maken](/nl/advanced/ai-sdk-custom-provider.md)
- [Upgradegids van Laravel 12 naar 13](/nl/blog/upgrade-12-to-13.md)