Modelli pivot personalizzati e chaperone

Cos’è un modello pivot personalizzato

La tabella intermedia di belongsToMany (molti-a-molti) è, per impostazione predefinita, trattata come una semplice istanza di Illuminate\Database\Eloquent\Relations\Pivot. Se vuoi che la tabella intermedia contenga colonne aggiuntive (data di approvazione, tipo di ruolo, ecc.) o se vuoi aggiungere accessor, mutator e metodi personalizzati, puoi creare un modello personalizzato che estende Pivot.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\Pivot;

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

Nella definizione di belongsToMany chiama using() per indicare alla relazione di usare questo modello personalizzato.

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

Quando salvi un modello pivot personalizzato, denomina la classe usando sempre il singolare in ordine alfabetico (RoleUser e non UserRole). Si tratta però di una convenzione di denominazione: sei libero di scegliere il nome effettivo della classe.

Specificare gli attributi da recuperare con `as()`

Per impostazione predefinita, i valori della tabella intermedia si consultano attraverso la proprietà pivot. Con il metodo as() puoi cambiare questo nome.

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

Colonne aggiuntive e timestamp

Se la tabella intermedia ha colonne aggiuntive come approved, includile esplicitamente tra quelle da recuperare con withPivot(). Per gestire created_at / updated_at, chiama withTimestamps().

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

Eloquent aggiorna automaticamente updated_at sulla tabella intermedia solo quando il modello pivot è specificato esplicitamente con using(). Anche usando la classe Pivot predefinita withTimestamps() funziona, ma specificando un modello personalizzato con using() puoi sfruttare eventi personalizzati, cast personalizzati e altro ancora.

Riferimenti inversi dal modello pivot

In un modello pivot personalizzato puoi definire liberamente relazioni belongsTo verso il modello dichiarante e il modello correlato.

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

In questo modo, anche quando ottieni un modello pivot in modo indipendente, puoi accedere ai modelli correlati con $roleUser->role o $roleUser->user. Se però vuoi che queste relazioni vengano eager loaded automaticamente al momento dell’esecuzione della query padre, puoi usare il metodo chaperone() descritto qui sotto.

Eager loading automatico con `chaperone()` (Laravel 13)

Laravel 13 ha aggiunto il metodo chaperone(), che permette di idratare automaticamente (l’equivalente dell’eager loading) le relazioni belongsTo come role() / user() definite sul modello pivot quando la query belongsToMany viene eseguita.

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

Quando chiami chaperone(), Eloquent deduce automaticamente i nomi delle relazioni belongsTo presenti sul modello pivot (RoleUser) e, quando recuperi una collezione con qualcosa come Role::with('users'), imposta senza query aggiuntive i riferimenti al modello dichiarante e al modello correlato per ciascun pivot.

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

foreach ($role->users as $user) {
    // Accedi al modello padre tramite il pivot senza query aggiuntive
    echo $user->pivot->role->name;
}

Quando i nomi delle relazioni non sono standard

Se il nome del metodo belongsTo sul modello pivot non segue la denominazione standard (camelCase singolare del nome del modello dichiarante o correlato), specificalo esplicitamente tramite gli argomenti di chaperone().

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

chaperone() è un meccanismo che risolve il “problema N+1” anche per i riferimenti che passano dalla tabella intermedia. Nelle applicazioni che consultano spesso informazioni del modello padre a partire dal pivot (ad esempio per mostrare insieme data di approvazione e nome utente), abbinarlo al classico eager loading con with() è particolarmente efficace.

Prossimi passi

Relazioni

Torna a rivedere come definire le relazioni di base, incluso belongsToMany.

Eloquent Observers ed eventi del modello

Impara come usare gli eventi del modello per intercettare salvataggi e aggiornamenti del modello pivot.

Sviluppo con AI

Design pattern

Sviluppo di pacchetti

Struttura dell'applicazione

Novità di Laravel 13

Approfondimento Eloquent

Estensione della validazione

Estensione dell'autenticazione

Sicurezza

Code

Test

Modelli pivot personalizzati e chaperone

Cos’è un modello pivot personalizzato

Specificare gli attributi da recuperare con `as()`

Colonne aggiuntive e timestamp

Riferimenti inversi dal modello pivot

Eager loading automatico con `chaperone()` (Laravel 13)

Quando i nomi delle relazioni non sono standard

Prossimi passi

Relazioni

Eloquent Observers ed eventi del modello

​Cos’è un modello pivot personalizzato

​Specificare gli attributi da recuperare con as()

​Colonne aggiuntive e timestamp

​Riferimenti inversi dal modello pivot

​Eager loading automatico con chaperone() (Laravel 13)

​Quando i nomi delle relazioni non sono standard

​Prossimi passi

Relazioni

Eloquent Observers ed eventi del modello

Cos’è un modello pivot personalizzato

Specificare gli attributi da recuperare con `as()`

Colonne aggiuntive e timestamp

Riferimenti inversi dal modello pivot

Eager loading automatico con `chaperone()` (Laravel 13)

Quando i nomi delle relazioni non sono standard

Prossimi passi