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

# Eigene Pivot-Modelle und chaperone

> Erläutert, wie Sie die Zwischentabelle einer belongsToMany-Relation als eigenes Pivot-Modell behandeln und in Laravel 13 mit chaperone automatisch Eager-Loading einsetzen.

## Was ist ein eigenes Pivot-Modell?

Die Zwischentabelle einer [belongsToMany-Relation (n:m)](/de/eloquent-relationships#belongstomany-nm) wird standardmäßig als reine `Illuminate\Database\Eloquent\Relations\Pivot`-Instanz behandelt. Möchten Sie in der Zwischentabelle zusätzliche Spalten (z. B. ein Freigabedatum oder eine Rollenart) führen oder Accessors, Mutators und eigene Methoden ergänzen, erstellen Sie ein eigenes Modell, das von `Pivot` erbt.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\Pivot;

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

In der Definition von `belongsToMany` rufen Sie anschließend `using()` auf, um der Relation dieses eigene Modell mitzuteilen.

```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>
  Achten Sie beim Speichern eines eigenen Pivot-Modells darauf, den Modellnamen stets als **alphabetisch sortierte Singularform** zu wählen (`RoleUser` statt `UserRole`). Das ist jedoch nur eine Namenskonvention – der tatsächliche Klassenname bleibt Ihnen überlassen.
</Info>

## Mit `as()` einen anderen Zugriffsnamen wählen

Standardmäßig greifen Sie über die Eigenschaft `pivot` auf die Werte der Zwischentabelle zu. Mit der Methode `as()` können Sie diesen Namen ändern.

```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;
}
```

## Zusätzliche Spalten und Timestamps

Enthält die Zwischentabelle zusätzliche Spalten wie `approved`, müssen Sie sie mit `withPivot()` explizit in den Abruf einbeziehen. Möchten Sie `created_at` / `updated_at` verwalten, rufen Sie `withTimestamps()` auf.

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

<Warning>
  Eloquent aktualisiert das `updated_at` der Zwischentabelle nur dann automatisch, wenn das entsprechende Pivot-Modell über `using()` explizit angegeben ist. `withTimestamps()` funktioniert zwar auch mit der Standardklasse `Pivot`, doch erst mit einem über `using()` angegebenen eigenen Modell stehen Ihnen zusätzliche Möglichkeiten wie eigene Events oder eigene Casts zur Verfügung.
</Warning>

## Rückverweise vom Pivot-Modell aus

Auf einem eigenen Pivot-Modell können Sie beliebige `belongsTo`-Relationen zum deklarierenden und zum verknüpften Modell definieren.

```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);
    }
}
```

Dadurch können Sie – selbst wenn Sie nur das Pivot-Modell allein abrufen – über `$roleUser->role` oder `$roleUser->user` auf die verknüpften Modelle zugreifen. Möchten Sie diese Relationen jedoch bereits beim Ausführen der übergeordneten Abfrage automatisch per Eager Loading laden, hilft die im Folgenden vorgestellte Methode `chaperone()`.

## Automatisches Eager Loading mit `chaperone()` (Laravel 13)

Mit Laravel 13 wurde die Methode `chaperone()` eingeführt. Sie hydratisiert die auf dem Pivot-Modell definierten `belongsTo`-Relationen wie `role()` / `user()` automatisch (vergleichbar mit Eager Loading), wenn die `belongsToMany`-Abfrage ausgeführt wird.

```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();
    }
}
```

Wird `chaperone()` aufgerufen, ermittelt Eloquent automatisch die Namen der `belongsTo`-Relationen des Pivot-Modells (`RoleUser`) und setzt beim Laden einer Collection wie `Role::with('users')` für jeden Pivot ohne zusätzliche Abfragen die Verweise auf das deklarierende und das verknüpfte Modell.

```php theme={null}
$role = Role::with('users')->first();

foreach ($role->users as $user) {
    // Ohne zusätzliche Abfrage lässt sich über den Pivot auf das Elternmodell zugreifen
    echo $user->pivot->role->name;
}
```

### Nicht-standardmäßige Relationsnamen verwenden

Weichen die Methodennamen der `belongsTo`-Relationen des Pivot-Modells von der Standardkonvention ab (CamelCase-Singularform des deklarierenden bzw. verknüpften Modellnamens), können Sie sie über die Argumente von `chaperone()` explizit angeben.

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

<Tip>
  `chaperone()` löst das „N+1-Problem" auch für Verweise über die Zwischentabelle. In Anwendungen, die häufig Informationen aus dem Elternmodell über den Pivot referenzieren (z. B. Freigabedatum und Benutzername gemeinsam anzeigen), lohnt sich der Einsatz in Kombination mit dem gewöhnlichen Eager Loading via `with()`.
</Tip>

## Nächste Schritte

<Card title="Eloquent-Beziehungen" icon="link" href="/de/eloquent-relationships">
  Wiederholen Sie die Definition grundlegender Relationen, einschließlich belongsToMany.
</Card>

<Card title="Eloquent-Observer und Model-Events" icon="bolt" href="/de/advanced/eloquent-observers">
  Erfahren Sie, wie Sie mit Model-Events das Speichern und Aktualisieren eines Pivot-Modells hooken.
</Card>


## Related topics

- [Einführung in Eloquent-Relationen](/de/eloquent-relationships.md)
- [Modelle](/de/packages/laravel-copilot-sdk/models.md)
- [Weiterführende Themen](/de/advanced/index.md)
- [Upgrade-Anleitung von Laravel 12 auf 13](/de/blog/upgrade-12-to-13.md)
- [Eigene Validierungsregeln](/de/advanced/custom-validation-rules.md)