Eloquent-Serialisierung - Knowledge of Laravel

Einführung

Beim Aufbau einer API mit Laravel müssen Sie Modelle und ihre Relationen häufig in Arrays oder JSON umwandeln. Eloquent bringt praktische Methoden für diese Umwandlung mit sowie Funktionen, mit denen Sie steuern, welche Attribute in der serialisierten Darstellung enthalten sind.

Eine robustere Möglichkeit, Eloquent-Modelle und -Collections nach JSON zu serialisieren, bietet die Dokumentation zu Eloquent-API-Ressourcen.

Modelle und Arrays

Serialisierung in ein Array

Um ein Modell und seine geladenen Relationen in ein Array umzuwandeln, verwenden Sie die Methode toArray. Die Methode arbeitet rekursiv: Alle Attribute und alle Relationen (inklusive verschachtelter Relationen) werden in ein Array überführt.

use App\Models\User;

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

return $user->toArray();

Mit attributesToArray konvertieren Sie ausschließlich die Attribute des Modells, ohne Relationen.

$user = User::first();

return $user->attributesToArray();

Eine gesamte Modell-Collection wandeln Sie über die Methode toArray der Collection-Instanz in ein Array um.

$users = User::all();

return $users->toArray();

Serialisierung in JSON

Mit der Methode toJson wandeln Sie ein Modell in JSON um. Wie toArray arbeitet toJson rekursiv – alle Attribute und Relationen werden in JSON überführt. Sie können die von PHP unterstützten JSON-Kodierungsoptionen übergeben.

use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

Sie können ein Modell oder eine Collection auch in einen String casten; dabei wird intern toJson aufgerufen.

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

Da Modelle und Collections beim Cast zu einem String in JSON umgewandelt werden, können Sie Eloquent-Objekte direkt aus Routen oder Controllern zurückgeben. Laravel serialisiert von Routen oder Controllern zurückgegebene Eloquent-Modelle und -Collections automatisch nach JSON.

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

Relationen

Wenn ein Eloquent-Modell in JSON umgewandelt wird, tauchen bereits geladene Relationen automatisch als Attribute im JSON-Objekt auf. Auch wenn Eloquent-Relationsmethoden im CamelCase definiert sind, verwenden ihre JSON-Attributnamen die Snake-Case-Schreibweise.

Sichtbarkeit von Attributen steuern

Attribute ausblenden

Manchmal möchten Sie in der Array- oder JSON-Darstellung eines Modells bestimmte Attribute – etwa Passwörter – ausblenden. Verwenden Sie hierfür das Attribut Hidden auf dem Modell. Attribute, die in Hidden aufgelistet sind, erscheinen nicht in der serialisierten Darstellung.

<?php

namespace App\Models;

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

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

Um Relationen auszublenden, tragen Sie den Namen der Relationsmethode in das Hidden-Attribut ein.

Attribute freigeben

Mit dem Attribut Visible legen Sie eine „Whitelist” der Attribute fest, die in Array- und JSON-Darstellungen enthalten sein sollen. Alle Attribute, die nicht in Visible aufgelistet sind, werden bei der Umwandlung in ein Array oder JSON ausgeblendet.

<?php

namespace App\Models;

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

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

Attribute temporär ein-/ausblenden

Um normalerweise verborgene Attribute auf einer bestimmten Modellinstanz sichtbar zu machen, verwenden Sie makeVisible oder mergeVisible. makeVisible liefert die Modellinstanz zurück.

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

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

Umgekehrt können Sie ansonsten sichtbare Attribute mit makeHidden oder mergeHidden verbergen.

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

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

Um sichtbare oder verborgene Attribute vollständig zu überschreiben, verwenden Sie setVisible bzw. setHidden.

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

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

Angehängte Attribute (Appends)

Bei der Umwandlung eines Modells in ein Array oder JSON möchten Sie manchmal Attribute hinzufügen, für die es keine passende Datenbankspalte gibt. Definieren Sie dazu zunächst einen Accessor für den gewünschten Wert.

<?php

namespace App\Models;

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

class User extends Model
{
    /**
     * Bestimme, ob der Benutzer Administrator ist.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

Wenn der Accessor immer in Array- und JSON-Darstellungen des Modells enthalten sein soll, verwenden Sie am Modell das Attribut Appends. Die PHP-Methode für den Accessor ist im CamelCase definiert; der Attributname folgt in der Serialisierung üblicherweise dem Snake-Case.

<?php

namespace App\Models;

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

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

Sobald ein Attribut in der appends-Liste steht, taucht es sowohl in der Array- als auch in der JSON-Darstellung auf. Auch Einträge in appends unterliegen den visible- und hidden-Einstellungen des Modells.

Zur Laufzeit anhängen

Zur Laufzeit können Sie einer Modellinstanz mit append oder mergeAppends zusätzliche Attribute anhängen. Mit setAppends überschreiben Sie das gesamte Array angehängter Eigenschaften für eine bestimmte Modellinstanz.

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

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

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

Um alle angehängten Eigenschaften wieder zu entfernen, verwenden Sie withoutAppends.

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

Datumsserialisierung

Standard-Datumsformat anpassen

Durch Überschreiben der Methode serializeDate passen Sie das Standard-Serialisierungsformat an. Auf das Speicherformat in der Datenbank hat diese Methode keinen Einfluss.

/**
 * Bereite ein Datum für die Array-/JSON-Serialisierung vor.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

Formatierung pro Attribut anpassen

Über die Cast-Deklarationen des Modells legen Sie das Serialisierungsformat einzelner Datumsattribute fest.

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

​Einführung

​Modelle und Arrays

​Serialisierung in ein Array

​Serialisierung in JSON

​Relationen

​Sichtbarkeit von Attributen steuern

​Attribute ausblenden

​Attribute freigeben

​Attribute temporär ein-/ausblenden

​Angehängte Attribute (Appends)

​Zur Laufzeit anhängen

​Datumsserialisierung

​Standard-Datumsformat anpassen

​Formatierung pro Attribut anpassen

Einführung

Modelle und Arrays

Serialisierung in ein Array

Serialisierung in JSON

Relationen

Sichtbarkeit von Attributen steuern

Attribute ausblenden

Attribute freigeben

Attribute temporär ein-/ausblenden

Angehängte Attribute (Appends)

Zur Laufzeit anhängen

Datumsserialisierung

Standard-Datumsformat anpassen

Formatierung pro Attribut anpassen