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

# Serializzazione Eloquent

> Come convertire i modelli Eloquent in JSON/array, controllare la visibilità degli attributi, aggiungere attributi supplementari e personalizzare il formato delle date.

## Introduzione

Quando costruisci un'API in Laravel, spesso devi convertire modelli e relazioni in array o JSON.
Eloquent include metodi comodi per queste conversioni e funzionalità per controllare quali attributi includere nella rappresentazione serializzata del modello.

<Info>
  Per una serializzazione JSON più robusta di modelli e collezioni Eloquent, consulta la documentazione delle [Eloquent API Resource](./eloquent-resources).
</Info>

## Modelli e array

### Serializzazione in array

Per convertire un modello e le [relazioni](./eloquent-relationships) caricate in un array usa il metodo `toArray`.
Il metodo lavora ricorsivamente, quindi tutti gli attributi e tutte le relazioni (incluse le relazioni delle relazioni) vengono convertiti in array.

```php theme={null}
use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();
```

Con `attributesToArray` converti in array i soli attributi del modello, escludendo le relazioni.

```php theme={null}
$user = User::first();

return $user->attributesToArray();
```

Per convertire in array un'intera collezione di modelli chiama `toArray` sull'istanza della collection.

```php theme={null}
$users = User::all();

return $users->toArray();
```

### Serializzazione in JSON

Per convertire un modello in JSON usa il metodo `toJson`.
Come `toArray`, anche `toJson` è ricorsivo: tutti gli attributi e le relazioni vengono convertiti in JSON.
Puoi indicare le [opzioni di codifica JSON supportate da PHP](https://secure.php.net/manual/en/function.json-encode.php).

```php theme={null}
use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);
```

Puoi anche fare il cast a stringa di un modello o di una collection: verrà chiamato automaticamente `toJson`.

```php theme={null}
return (string) User::find(1);
```

Poiché modelli e collection castati a stringa diventano JSON, puoi restituire direttamente gli oggetti Eloquent da route o controller.
Laravel serializza automaticamente in JSON i modelli e le collection Eloquent restituiti da route o controller.

```php theme={null}
Route::get('/users', function () {
    return User::all();
});
```

#### Relazioni

Quando un modello Eloquent viene convertito in JSON, le relazioni caricate vengono incluse automaticamente come attributi dell'oggetto JSON.
Inoltre, i metodi di relazione Eloquent sono definiti in "camelCase" ma gli attributi JSON delle relazioni sono in "snake\_case".

## Controllo della visibilità degli attributi

### Nascondere attributi

Potresti voler limitare gli attributi (come le password) inclusi nella rappresentazione ad array o JSON del modello.
Per farlo usa l'attribute `Hidden` sul modello.
Gli attributi elencati non appariranno nella rappresentazione serializzata.

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

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}
```

<Info>
  Per nascondere una relazione, aggiungi il nome del metodo della relazione all'attribute `Hidden` del modello.
</Info>

### Rendere visibili attributi

Con l'attribute `Visible` puoi definire un "elenco di consentiti" degli attributi che devono comparire nella rappresentazione ad array e JSON del modello.
Tutti gli attributi non presenti in `Visible` vengono nascosti quando il modello viene convertito in array o JSON.

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

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}
```

### Visibilità temporanea di attributi

Per rendere visibile su una singola istanza un attributo normalmente nascosto usa `makeVisible` o `mergeVisible`.
`makeVisible` restituisce l'istanza del modello.

```php theme={null}
return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();
```

Al contrario, per nascondere un attributo normalmente visibile usa `makeHidden` o `mergeHidden`.

```php theme={null}
return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();
```

Per sovrascrivere temporaneamente tutti gli attributi visibili o nascosti usa `setVisible` e `setHidden`.

```php theme={null}
return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();
```

## Attributi aggiuntivi

Quando converti un modello in array o JSON, potresti voler aggiungere attributi che non hanno una colonna corrispondente nel database.
Per farlo definisci prima un [accessor](./eloquent-mutators) per il valore.

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

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Indica se l'utente è amministratore.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}
```

Per aggiungere sempre l'accessor alla rappresentazione ad array e JSON del modello, usa l'attribute `Appends` sul modello.
Anche se il metodo PHP dell'accessor è in "camelCase", il nome dell'attributo di norma nella rappresentazione serializzata è in "snake\_case".

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

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}
```

Una volta aggiunto all'elenco `appends`, l'attributo è incluso nella rappresentazione ad array e JSON del modello.
Anche gli attributi in `appends` rispettano le impostazioni `visible` e `hidden` del modello.

### Aggiunta a runtime

A runtime puoi indicare all'istanza del modello di aggiungere attributi con i metodi `append` o `mergeAppends`.
Con `setAppends` puoi sovrascrivere l'intero array di proprietà appended per una specifica istanza.

```php theme={null}
return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();
```

Per rimuovere tutte le proprietà appended dal modello usa `withoutAppends`.

```php theme={null}
return $user->withoutAppends()->toArray();
```

## Serializzazione delle date

### Personalizzare il formato predefinito delle date

Sovrascrivendo `serializeDate` puoi personalizzare il formato predefinito di serializzazione.
Questo metodo non incide sul formato di salvataggio nel database.

```php theme={null}
/**
 * Prepara una data per la serializzazione in array/JSON.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}
```

### Personalizzare il formato per singolo attributo

Puoi personalizzare il formato di serializzazione dei singoli attributi data indicandolo nella [dichiarazione dei cast](./eloquent-mutators#attribute-casting) del modello.

```php theme={null}
protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}
```


## Related topics

- [Collezioni Eloquent](/it/eloquent-collections.md)
- [Accessor, mutator e cast di Eloquent](/it/eloquent-mutators.md)
- [Attributi PHP](/it/advanced/php-attributes.md)
- [Guida all'aggiornamento da Laravel 12 a 13](/it/blog/upgrade-12-to-13.md)
- [Eventi e listener](/it/events.md)