Eloquent-serialisatie

Aan de slag

Bij het bouwen van een API met Laravel moet je modellen en hun relaties vaak omzetten naar arrays of JSON. Eloquent bevat handige methoden voor deze conversies, plus functionaliteit om te bepalen welke attributen in de geserialiseerde weergave van je modellen worden opgenomen.

Zie de documentatie over Eloquent API-resources voor een robuustere manier om Eloquent-modellen en -collecties naar JSON te serialiseren.

Modellen en arrays

Serialiseren naar een array

Gebruik de toArray-methode om een model en de geladen relaties om te zetten naar een array. Deze methode werkt recursief: alle attributen en alle relaties (inclusief relaties van relaties) worden naar arrays omgezet.

use App\Models\User;

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

return $user->toArray();

Met de attributesToArray-methode kun je alleen de attributen van het model, zonder de relaties, omzetten naar een array.

$user = User::first();

return $user->attributesToArray();

Om een hele collectie modellen om te zetten naar een array, roep je de toArray-methode aan op de collectie-instantie.

$users = User::all();

return $users->toArray();

Serialiseren naar JSON

Gebruik de toJson-methode om een model naar JSON om te zetten. Net als toArray werkt toJson recursief, dus alle attributen en relaties worden naar JSON omgezet. Je kunt ook de JSON-encodeeropties die PHP ondersteunt opgeven.

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

Je kunt een model of collectie ook naar een string casten; in dat geval wordt de toJson-methode van het model of de collectie automatisch aangeroepen.

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

Omdat modellen en collecties bij het casten naar een string naar JSON worden omgezet, kun je Eloquent-objecten rechtstreeks teruggeven vanuit de routes en controllers van je applicatie. Laravel serialiseert Eloquent-modellen en -collecties die vanuit routes en controllers worden teruggegeven automatisch naar JSON.

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

Relaties

Wanneer een Eloquent-model naar JSON wordt omgezet, worden de geladen relaties automatisch opgenomen als attributen van het JSON-object. Verder worden Eloquent-relatiemethoden gedefinieerd met “camelCase”-methodenamen, maar het JSON-attribuut van een relatie is in “snake_case”.

Zichtbaarheid van attributen beheren

Attributen verbergen

Soms wil je attributen zoals wachtwoorden uitsluiten van de array- of JSON-weergave van je model. Gebruik daarvoor het Hidden-attribuut op je model. Attributen die in het Hidden-attribuut staan, worden niet opgenomen in de geserialiseerde weergave van het model.

<?php

namespace App\Models;

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

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

Om een relatie te verbergen, voeg je de methodenaam van de relatie toe aan het Hidden-attribuut van het Eloquent-model.

Attributen zichtbaar maken

Met het Visible-attribuut kun je ook een “toelatingslijst” definiëren van attributen die in de array- en JSON-weergave van je model moeten worden opgenomen. Alle attributen die niet in het Visible-attribuut staan, worden verborgen wanneer het model naar een array of JSON wordt omgezet.

<?php

namespace App\Models;

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

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

Attributen tijdelijk tonen of verbergen

Om attributen die normaal verborgen zijn zichtbaar te maken op een specifieke modelinstantie, gebruik je de methoden makeVisible of mergeVisible. De makeVisible-methode geeft de modelinstantie terug.

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

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

Omgekeerd kun je attributen die normaal zichtbaar zijn verbergen met de methoden makeHidden of mergeHidden.

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

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

Om alle zichtbare of verborgen attributen tijdelijk te overschrijven, gebruik je respectievelijk de methoden setVisible en setHidden.

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

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

Extra attributen

Bij het omzetten van een model naar een array of JSON wil je soms attributen toevoegen waarvoor geen kolom in de database bestaat. Definieer daarvoor eerst een accessor voor de waarde.

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Bepaal of de gebruiker een beheerder is.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

Wil je de accessor altijd toevoegen aan de array- en JSON-weergave van het model, gebruik dan het Appends-attribuut op je model. De PHP-methode van de accessor is gedefinieerd in “camelCase”, maar voor de attribuutnaam gebruik je gewoonlijk de geserialiseerde weergave 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
{
    // ...
}

Zodra een attribuut aan de appends-lijst is toegevoegd, wordt het opgenomen in zowel de array- als de JSON-weergave van het model. Attributen in de appends-array respecteren ook de visible- en hidden-instellingen van het model.

Toevoegen tijdens runtime

Tijdens runtime kun je met de methoden append of mergeAppends een modelinstantie opdragen extra attributen toe te voegen. Ook kun je met de setAppends-methode de volledige array van extra properties van een specifieke modelinstantie overschrijven.

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

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

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

Om alle toegevoegde properties van een model te verwijderen, gebruik je de withoutAppends-methode.

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

Serialisatie van datums

Het standaarddatumformaat aanpassen

Door de serializeDate-methode te overriden, kun je het standaardserialisatieformaat aanpassen. Deze methode heeft geen invloed op het datumformaat voor opslag in de database.

/**
 * Bereid een datum voor op array-/JSON-serialisatie.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

Het datumformaat per attribuut aanpassen

Door het datumformaat op te geven in de cast-declaraties van je model, kun je het serialisatieformaat van individuele Eloquent-datumattributen aanpassen.

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

Architectuur

Database

Eloquent

Beveiliging

Events

E-mail en notificaties

Betalingen

Asynchrone verwerking

Realtime communicatie

Taakplanning

Caching en optimalisatie

Internationalisatie

Bestanden en opslag

Debugging en monitoring

Console en CLI

Performance

Frontend

AI-ontwikkeling

Ontwikkelomgeving

Aan de slag

Modellen en arrays

Serialiseren naar een array

Serialiseren naar JSON

Relaties

Zichtbaarheid van attributen beheren

Attributen verbergen

Attributen zichtbaar maken

Attributen tijdelijk tonen of verbergen

Extra attributen

Toevoegen tijdens runtime

Serialisatie van datums

Het standaarddatumformaat aanpassen

Het datumformaat per attribuut aanpassen

​Aan de slag

​Modellen en arrays

​Serialiseren naar een array

​Serialiseren naar JSON

​Relaties

​Zichtbaarheid van attributen beheren

​Attributen verbergen

​Attributen zichtbaar maken

​Attributen tijdelijk tonen of verbergen

​Extra attributen

​Toevoegen tijdens runtime

​Serialisatie van datums

​Het standaarddatumformaat aanpassen

​Het datumformaat per attribuut aanpassen

Aan de slag

Modellen en arrays

Serialiseren naar een array

Serialiseren naar JSON

Relaties

Zichtbaarheid van attributen beheren

Attributen verbergen

Attributen zichtbaar maken

Attributen tijdelijk tonen of verbergen

Extra attributen

Toevoegen tijdens runtime

Serialisatie van datums

Het standaarddatumformaat aanpassen

Het datumformaat per attribuut aanpassen