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

# Modelli pivot personalizzati e chaperone

> Come trattare la tabella intermedia di belongsToMany come un modello Pivot personalizzato e come usare chaperone, aggiunto in Laravel 13, per l'eager loading automatico.

## Cos'è un modello pivot personalizzato

La tabella intermedia di [belongsToMany (molti-a-molti)](/it/eloquent-relationships#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 theme={null}
<?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 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>
  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.
</Info>

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

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

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

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

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

## Riferimenti inversi dal modello pivot

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

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

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

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.

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

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

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

## Prossimi passi

<Card title="Relazioni" icon="link" href="/it/eloquent-relationships">
  Torna a rivedere come definire le relazioni di base, incluso belongsToMany.
</Card>

<Card title="Eloquent Observers ed eventi del modello" icon="bolt" href="/it/advanced/eloquent-observers">
  Impara come usare gli eventi del modello per intercettare salvataggi e aggiornamenti del modello pivot.
</Card>


## Related topics

- [Introduzione alle relazioni Eloquent](/it/eloquent-relationships.md)
- [Modelli](/it/packages/laravel-copilot-sdk/models.md)
- [Guida all'aggiornamento da Laravel 12 a 13](/it/blog/upgrade-12-to-13.md)
- [Agenti personalizzati](/it/packages/laravel-copilot-sdk/custom-agents.md)
- [Provider personalizzati](/it/packages/laravel-copilot-sdk/custom-providers.md)