Serializzazione Eloquent - Knowledge of Laravel

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',
    ];
}

​Introduzione

​Modelli e array

​Serializzazione in array

​Serializzazione in JSON

​Relazioni

​Controllo della visibilità degli attributi

​Nascondere attributi

​Rendere visibili attributi

​Visibilità temporanea di attributi

​Attributi aggiuntivi

​Aggiunta a runtime

​Serializzazione delle date

​Personalizzare il formato predefinito delle date

​Personalizzare il formato per singolo attributo

Introduzione

Modelli e array

Serializzazione in array

Serializzazione in JSON

Relazioni

Controllo della visibilità degli attributi

Nascondere attributi

Rendere visibili attributi

Visibilità temporanea di attributi

Attributi aggiuntivi

Aggiunta a runtime

Serializzazione delle date

Personalizzare il formato predefinito delle date

Personalizzare il formato per singolo attributo