JSON ist heute das Standardformat für den Datenaustausch im Web. Ob REST-APIs, Konfigurationsdateien oder die Kommunikation zwischen Frontend und Backend: überall kommt JSON zum Einsatz. PHP bietet mit json_encode() eine leistungsfähige Funktion, um PHP-Datenstrukturen in JSON-Strings umzuwandeln. In diesem Tutorial lernst du die Syntax, die wichtigsten Optionen und die Fehlerbehandlung rund um json_encode(). Außerdem wird json_decode() als Gegenstück vorgestellt, um JSON-Strings wieder in PHP-Werte zurückzuverwandeln.
Bevor es um die PHP-Funktion selbst geht, wird kurz erklärt, was JSON eigentlich ist und warum sich das Format als Standard durchgesetzt hat.
Was ist JSON?
JSON steht für JavaScript Object Notation und ist ein leichtgewichtiges Textformat zur Darstellung strukturierter Daten. Trotz des Namens ist JSON sprachunabhängig und wird in nahezu allen Programmiersprachen unterstützt. JSON kennt einfache Datentypen wie Strings, Zahlen, Booleans und null sowie zusammengesetzte Typen wie Objekte (Schlüssel-Wert-Paare in geschweiften Klammern) und Arrays (geordnete Listen in eckigen Klammern). Durch seine Einfachheit und gute Lesbarkeit hat JSON das früher verbreitete XML in vielen Bereichen abgelöst.
Syntax und Grundlagen von json_encode
Die Funktion json_encode() nimmt einen PHP-Wert entgegen und gibt den entsprechenden JSON-String zurück. Als optionalen zweiten Parameter akzeptiert sie Flags, die das Verhalten steuern. Ein dritter Parameter legt die maximale Verschachtelungstiefe fest.
Das folgende Diagramm zeigt den typischen Ablauf bei der Arbeit mit JSON in PHP.
flowchart TD
A[PHP-Array] -->|json_encode| B[JSON]
B -->|Speichern| C[DB / API / Datei]
C -->|Empfangen| D[JSON]
D -->|json_decode| E[PHP-Array]
Der Kreislauf beginnt mit einer PHP-Datenstruktur, die per json_encode() in einen JSON-String umgewandelt wird. Dieser String kann gespeichert, über eine API gesendet oder in einer Datei abgelegt werden. Beim Empfang wird der JSON-String mit json_decode() wieder in eine PHP-Datenstruktur umgewandelt.
Arrays und Objekte kodieren
PHP unterscheidet zwischen numerischen und assoziativen Arrays. Diese Unterscheidung wirkt sich direkt auf das erzeugte JSON aus.
Assoziative vs. numerische Arrays
Ein assoziatives Array wird von json_encode() als JSON-Objekt dargestellt, während ein numerisches Array als JSON-Array ausgegeben wird.
<?php
$daten = ['name' => 'Max', 'alter' => 28, 'stadt' => 'Berlin'];
$json = json_encode($daten);
echo $json;
/* {"name":"Max","alter":28,"stadt":"Berlin"} */
Hier erzeugt json_encode() ein JSON-Objekt mit Schlüssel-Wert-Paaren, weil das PHP-Array assoziative Schlüssel besitzt. Ein numerisches Array wie ['Apfel', 'Birne', 'Kirsche'] würde hingegen als JSON-Array ["Apfel","Birne","Kirsche"] ausgegeben. Diese automatische Erkennung ist in den meisten Fällen praktisch, kann aber mit der Option JSON_FORCE_OBJECT überschrieben werden.
PHP-Objekte als JSON
PHP-Objekte werden von json_encode() anhand ihrer öffentlichen Eigenschaften in JSON-Objekte umgewandelt. Private und geschützte Eigenschaften sind im JSON nicht enthalten. Wer die Ausgabe kontrollieren möchte, kann das Interface JsonSerializable implementieren und in der Methode jsonSerialize() festlegen, welche Daten im JSON erscheinen sollen.
Die wichtigsten json_encode-Optionen
PHP bietet zahlreiche Flags, um das Verhalten von json_encode() anzupassen. Diese Flags lassen sich mit dem Pipe-Operator (|) kombinieren.
JSON_PRETTY_PRINT
Das Flag JSON_PRETTY_PRINT formatiert die Ausgabe mit Einrückungen und Zeilenumbrüchen. Das ist besonders nützlich für die Entwicklung und das Debugging.
<?php
$produkte = [
['id' => 1, 'name' => 'Laptop', 'preis' => 999.99],
['id' => 2, 'name' => 'Maus', 'preis' => 29.90]
];
echo json_encode($produkte, JSON_PRETTY_PRINT);
Die Ausgabe enthält dann Einrückungen mit vier Leerzeichen pro Ebene. In Produktivumgebungen sollte auf JSON_PRETTY_PRINT verzichtet werden, da die zusätzlichen Leerzeichen und Zeilenumbrüche die Dateigröße unnötig erhöhen.
JSON_UNESCAPED_UNICODE
Standardmäßig escaped json_encode() Unicode-Zeichen in die Form uXXXX. Mit JSON_UNESCAPED_UNICODE bleiben die Zeichen in ihrer ursprünglichen UTF-8-Darstellung erhalten.
<?php
$text = ['nachricht' => 'Gruesse aus Muenchen'];
echo json_encode($text);
/* Umlaute werden escaped: {"nachricht":"Gr\u00fc\u00dfe aus M\u00fcnchen"} */
echo json_encode($text, JSON_UNESCAPED_UNICODE);
/* {"nachricht":"Gruesse aus Muenchen"} */
Wichtig ist, dass die Eingabedaten in UTF-8 kodiert sein müssen. Nicht-UTF-8-Strings führen dazu, dass json_encode() false zurückgibt und einen Fehler setzt.
JSON_FORCE_OBJECT
Das Flag JSON_FORCE_OBJECT erzwingt die Ausgabe als JSON-Objekt, selbst wenn das PHP-Array numerische Schlüssel hat. Aus ["Apfel","Birne"] wird dann {"0":"Apfel","1":"Birne"}. Das kann nützlich sein, wenn eine API zwingend ein Objekt erwartet.
JSON_NUMERIC_CHECK
Mit JSON_NUMERIC_CHECK werden numerische Strings automatisch als Zahlen kodiert. Dabei ist Vorsicht geboten: Postleitzahlen wie "01234" würden fälschlicherweise als Zahl 1234 interpretiert und verlieren dabei die führende Null. Dieses Flag sollte daher nur eingesetzt werden, wenn sichergestellt ist, dass keine numerischen Strings mit spezieller Bedeutung in den Daten vorkommen.
Fehlerbehandlung mit json_last_error
Die Funktion json_encode() gibt im Fehlerfall false zurück. Um die genaue Fehlerursache zu ermitteln, stehen die Funktionen json_last_error() und json_last_error_msg() zur Verfügung.
<?php
$ergebnis = json_encode($daten);
if ($ergebnis === false) {
echo 'JSON-Fehler: ' . json_last_error_msg();
}
Häufige Fehlerursachen sind nicht-UTF-8-kodierte Strings, zu tiefe Verschachtelungen oder nicht unterstützte Datentypen wie Ressourcen. Ab PHP 7.3 kann alternativ das Flag JSON_THROW_ON_ERROR verwendet werden. Damit wirft json_encode() bei einem Fehler eine JsonException, die sich mit einem try-catch-Block abfangen lässt. Das ist besonders in größeren Anwendungen praktisch, da Fehler so nicht übersehen werden können.
json_decode: JSON zurück in PHP
Das Gegenstück zu json_encode() ist json_decode(). Diese Funktion wandelt einen JSON-String in einen PHP-Wert um. Standardmäßig gibt json_decode() ein Objekt vom Typ stdClass zurück. Mit dem zweiten Parameter true wird stattdessen ein assoziatives Array erzeugt.
<?php
$json = '{"name":"Max","alter":28}';
$objekt = json_decode($json);
echo $objekt->name; /* Max */
$array = json_decode($json, true);
echo $array['name']; /* Max */
Beide Varianten haben ihre Berechtigung. Objekte eignen sich gut für den lesenden Zugriff, während assoziative Arrays flexibler sind, wenn die Daten weiterverarbeitet oder verändert werden sollen. Die Fehlerbehandlung funktioniert bei json_decode() genauso wie bei json_encode() mit json_last_error() und json_last_error_msg().
Fazit
Die Funktion json_encode() ist ein unverzichtbares Werkzeug in der PHP-Entwicklung. Sie wandelt PHP-Arrays und Objekte zuverlässig in JSON-Strings um, die sich speichern, übertragen und von anderen Systemen verarbeiten lassen. Mit den verschiedenen Flags wie JSON_PRETTY_PRINT, JSON_UNESCAPED_UNICODE und JSON_THROW_ON_ERROR lässt sich die Ausgabe präzise steuern. Zusammen mit json_decode() bildet json_encode() ein starkes Duo für die Arbeit mit JSON in PHP. Dabei sollte stets auf korrekte UTF-8-Kodierung geachtet und die Rückgabewerte auf Fehler geprüft werden.
