Serializzazione

• Introduzione
• Serializzazione di Modelli e Collezioni
• Nascondere Attributi nel JSON
• Aggiungere Valori al JSON
• Serializzazione delle date

Introduzione

Quando si costruiscono API usando Laravel, spesso è necessario convertire i modelli e le relazioni in array o JSON. Eloquent include metodi comodi per effettuare queste conversioni, oltre a controllare quali attributi sono inclusi nella rappresentazione serializzata dei tuoi modelli.

Per un modo ancora più robusto di gestire la serializzazione JSON dei modelli Eloquent e delle collezioni, consulta la documentazione su Eloquent API resources.

<a name="serializzazione-di-modelli-e-collezioni"></a>
## Serializzazione di Modelli e Collezioni

<a name="serializzazione-in-array"></a>
### Serializzazione in Array

Per convertire un modello e le sue [relazioni](https://laravel-italia.it/documentazione-laravel-11-x-relazioni) caricate in un array, usa il metodo `toArray`. Questo metodo è ricorsivo, quindi tutti gli attributi e tutte le relazioni (comprese quelle delle relazioni) saranno convertiti in array:

```php
use App\Models\User;

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

return $user->toArray();

Il metodo attributesToArray può essere usato per convertire gli attributi di un modello in un array, ma non le sue relazioni:

$user = User::first();

return $user->attributesToArray();

Puoi anche convertire intere collezioni di modelli in array chiamando il metodo toArray sull’istanza della collezione:

$users = User::all();

return $users->toArray();

Serializzazione in JSON

Per convertire un modello in JSON, dovresti usare il metodo toJson. Come toArray, il metodo toJson è ricorsivo, quindi tutti gli attributi e le relazioni saranno convertiti in JSON. Puoi anche specificare qualsiasi opzione di codifica JSON supportata da PHP:

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

In alternativa, puoi convertire un modello o una collezione in una stringa, il che richiamerà automaticamente il metodo toJson sul modello o sulla collezione:

return (string) User::find(1);

Poiché i modelli e le collezioni vengono convertiti in JSON quando vengono trasformati in una stringa, puoi restituire direttamente oggetti Eloquent dalle rotte o dai controller della tua applicazione. Laravel serializzerà automaticamente i tuoi modelli e collezioni Eloquent in JSON quando vengono restituiti dalle rotte o dai controller:

Route::get('/users', function () {
    return User::all();
});

Relazioni

Quando un modello Eloquent viene convertito in JSON, le sue relazioni caricate saranno automaticamente incluse come attributi sull’oggetto JSON. Inoltre, anche se i metodi delle relazioni Eloquent sono definiti usando nomi di metodo in "camel case", l’attributo JSON di una relazione sarà in "snake case".

Nascondere Attributi nel JSON

A volte potresti voler limitare gli attributi, come le password, inclusi nella rappresentazione array o JSON del tuo modello. Per farlo, aggiungi una proprietà $hidden al tuo modello. Gli attributi elencati nell’array della proprietà $hidden non saranno inclusi nella rappresentazione serializzata del tuo modello:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Gli attributi che devono essere nascosti durante la serializzazione.
     *
     * @var array<string>
     */
    protected $hidden = ['password'];
}

Per nascondere le relazioni, aggiungi il nome del metodo della relazione alla proprietà $hidden del tuo modello Eloquent.

In alternativa, puoi usare la proprietà visible per definire una "lista autorizzata" di attributi che devono essere inclusi nella rappresentazione array e JSON del tuo modello. Tutti gli attributi non presenti nell’array $visible saranno nascosti quando il modello viene convertito in array o JSON:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Gli attributi che devono essere visibili negli array.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

Modificare Temporaneamente la Visibilità degli Attributi

Se desideri rendere visibili alcuni attributi tipicamente nascosti in un’istanza del modello, puoi usare il metodo makeVisible. Il metodo makeVisible restituisce l’istanza del modello:

    return $user->makeVisible('attribute')->toArray();

Allo stesso modo, se desideri nascondere alcuni attributi che sono tipicamente visibili, puoi usare il metodo makeHidden:

    return $user->makeHidden('attribute')->toArray();

Se vuoi sovrascrivere temporaneamente tutti gli attributi visibili o nascosti, puoi usare i metodi setVisible e setHidden rispettivamente:

    return $user->setVisible(['id', 'name'])->toArray();

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

Aggiungere Valori al JSON

Occasionalmente, quando si convertono i modelli in array o JSON, potresti voler aggiungere attributi che non hanno una colonna corrispondente nel tuo database. Per fare ciò, prima definisci un accessor per il valore:

    <?php

    namespace App\Models;

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

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

Se desideri che l’accessor venga sempre aggiunto alle rappresentazioni array e JSON del tuo modello, puoi aggiungere il nome dell’attributo alla proprietà appends del tuo modello. Nota che i nomi degli attributi sono tipicamente referenziati usando la loro rappresentazione serializzata in "snake case", anche se il metodo PHP dell’accessor è definito usando il "camel case":

    <?php

    namespace App\Models;

    use Illuminate\Database\Eloquent\Model;

    class User extends Model
    {
        /**
         * Gli accessor da aggiungere alla forma array del modello.
         *
         * @var array
         */
        protected $appends = ['is_admin'];
    }

Una volta che l’attributo è stato aggiunto alla lista appends, sarà incluso sia nelle rappresentazioni array che JSON del modello. Gli attributi nella lista appends rispetteranno anche le impostazioni visible e hidden configurate sul modello.

Aggiunta a runtime

Durante l’esecuzione, puoi istruire un’istanza di modello ad aggiungere attributi aggiuntivi usando il metodo append. Oppure, puoi usare il metodo setAppends per sovrascrivere l’intero array di proprietà aggiunte per una determinata istanza di modello:

return $user->append('is_admin')->toArray();

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

Serializzazione delle date

Personalizzare il formato data predefinito

Puoi personalizzare il formato di serializzazione predefinito sovrascrivendo il metodo serializeDate. Questo metodo non influisce su come le tue date sono formattate per l’archiviazione nel database:

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

Personalizzare il formato della data per attributo

Puoi personalizzare il formato di serializzazione delle singole date Eloquent specificando il formato della data nelle dichiarazioni di cast del modello:

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