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.

Per una serializzazione JSON più robusta di modelli e collezioni Eloquent, consulta la documentazione delle Eloquent API Resource.

​

Modelli e array

​

Serializzazione in array

Per convertire un modello e le relazioni 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.

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.

$user = User::first();

return $user->attributesToArray();

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

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

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.

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.

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

namespace App\Models;

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

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

Per nascondere una relazione, aggiungi il nome del metodo della relazione all’attribute Hidden del modello.

​

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

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.

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

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

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

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

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

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

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 per il valore.

<?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

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.

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.

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.

/**
 * 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 del modello.

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