Eigene Pivot-Modelle und chaperone

Was ist ein eigenes Pivot-Modell?

Die Zwischentabelle einer belongsToMany-Relation (n:m) 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

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

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

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.

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.

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

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.

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

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.

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

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

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.

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

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

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().

Nächste Schritte

Eloquent-Beziehungen

Wiederholen Sie die Definition grundlegender Relationen, einschließlich belongsToMany.

Eloquent-Observer und Model-Events

Erfahren Sie, wie Sie mit Model-Events das Speichern und Aktualisieren eines Pivot-Modells hooken.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Warteschlangen

Tests

Was ist ein eigenes Pivot-Modell?

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

Zusätzliche Spalten und Timestamps

Rückverweise vom Pivot-Modell aus

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

Nicht-standardmäßige Relationsnamen verwenden

Nächste Schritte

Eloquent-Beziehungen

Eloquent-Observer und Model-Events

​Was ist ein eigenes Pivot-Modell?

​Mit as() einen anderen Zugriffsnamen wählen

​Zusätzliche Spalten und Timestamps

​Rückverweise vom Pivot-Modell aus

​Automatisches Eager Loading mit chaperone() (Laravel 13)

​Nicht-standardmäßige Relationsnamen verwenden

​Nächste Schritte

Eloquent-Beziehungen

Eloquent-Observer und Model-Events

Was ist ein eigenes Pivot-Modell?

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

Zusätzliche Spalten und Timestamps

Rückverweise vom Pivot-Modell aus

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

Nicht-standardmäßige Relationsnamen verwenden

Nächste Schritte