Signatur
Beschreibung
JsonSerializable ist ein eingebautes PHP-Interface mit genau einer Methode: jsonSerialize(). Implementiert eine Klasse dieses Interface, ruft json_encode() automatisch jsonSerialize() auf dem Objekt auf und verwendet den zurückgegebenen Wert als Basis für die JSON-Kodierung – anstatt alle öffentlichen Eigenschaften zu serialisieren.
Das ist besonders nützlich, wenn:
- nur ein Teil der Eigenschaften in die JSON-Ausgabe einfließen soll (z. B. Passwörter oder interne Felder ausblenden),
- die JSON-Struktur von der internen Objektstruktur abweichen soll (z. B. umbenannte Schlüssel, berechnete Felder),
- verschachtelte Objekte in einfache Datentypen (Arrays, Strings) umgewandelt werden müssen.
Die Methode jsonSerialize() darf einen beliebigen JSON-kodierbaren Wert zurückgeben – in der Praxis fast immer ein assoziatives Array oder ein weiteres Objekt. Der zurückgegebene Wert wird dann von json_encode() normal weiterverarbeitet.
Ohne Implementierung von JsonSerializable serialisiert json_encode() alle öffentlichen Eigenschaften eines Objekts, was bei vielen Klassen nicht dem gewünschten Verhalten entspricht.
Beispiele
Passwort-Feld aus JSON-Ausgabe ausblenden
<?php
class Benutzer implements JsonSerializable
{
public function __construct(
private string $name,
private string $email,
private string $passwort
) {}
public function jsonSerialize(): mixed
{
return [
'name' => $this->name,
'email' => $this->email,
// $this->passwort wird bewusst weggelassen
];
}
}
$benutzer = new Benutzer('Anna Müller', 'anna@example.com', 'geheim123');
echo json_encode($benutzer, JSON_PRETTY_PRINT);Berechnete Felder und umstrukturierte JSON-Ausgabe
<?php
class Produkt implements JsonSerializable
{
public function __construct(
private string $bezeichnung,
private float $nettoPreis,
private float $mwstSatz = 0.19
) {}
public function getBruttoPreis(): float
{
return round($this->nettoPreis * (1 + $this->mwstSatz), 2);
}
public function jsonSerialize(): mixed
{
return [
'name' => $this->bezeichnung,
'netto' => $this->nettoPreis,
'brutto' => $this->getBruttoPreis(),
'mwst_prozent' => $this->mwstSatz * 100,
];
}
}
$produkt = new Produkt('Kaffeemaschine', 84.03);
echo json_encode($produkt, JSON_PRETTY_PRINT);Verschachtelte JsonSerializable-Objekte
<?php
class Adresse implements JsonSerializable
{
public function __construct(
private string $strasse,
private string $plz,
private string $ort
) {}
public function jsonSerialize(): mixed
{
return [
'strasse' => $this->strasse,
'plz' => $this->plz,
'ort' => $this->ort,
];
}
}
class Kunde implements JsonSerializable
{
public function __construct(
private string $name,
private Adresse $adresse
) {}
public function jsonSerialize(): mixed
{
return [
'name' => $this->name,
'adresse' => $this->adresse, // json_encode ruft auch hier jsonSerialize() auf
];
}
}
$kunde = new Kunde('Max Muster', new Adresse('Hauptstr. 1', '10115', 'Berlin'));
echo json_encode($kunde, JSON_PRETTY_PRINT);// Wichtig · Fallstricke
Rückgabetyp von jsonSerialize(): Ab PHP 8.0 lautet der deklarierte Rückgabetyp mixed. In PHP 5.4–7.x war kein Rückgabetyp im Interface angegeben. Zurückgegeben werden darf jeder von json_encode() verarbeitbare Wert (Array, String, Zahl, bool, null, weiteres Objekt).
Sicherheit: Ohne JsonSerializable werden alle öffentlichen Eigenschaften serialisiert – das kann sensible Daten wie API-Schlüssel, Passwörter oder interne IDs preisgeben. Bei Klassen, die JSON-Antworten liefern, sollte immer geprüft werden, ob eine explizite Serialisierungslogik notwendig ist.
Kein Einfluss auf json_decode(): Das Interface betrifft ausschließlich die Kodierung. Für das Deserialisieren von JSON zurück in Objekte ist manueller Code oder eine externe Bibliothek erforderlich.
Reihenfolge der Schlüssel: Die Reihenfolge der Schlüssel im zurückgegebenen Array bestimmt die Reihenfolge im JSON-Output.