JSON-Kodierung mit PHP

JSON (JavaScript Object Notation) ist ein leichtgewichtiges, textbasiertes Datenaustauschformat, das für Menschen leicht lesbar und für Maschinen einfach zu verarbeiten ist. Es ist das De-facto-Format für die Datenübertragung zwischen Server und Browser, für REST APIs und für Konfigurationsdateien. In PHP nimmt json_encode() einen PHP-Wert — einen Skalar, ein Array oder ein Objekt — und gibt dessen JSON-Darstellung als string zurück.

Diese Seite behandelt die Syntax, die nützlichsten $flags, wie PHP-Typen auf JSON abgebildet werden und wie Kodierungsfehler erkannt werden. Den umgekehrten Weg (JSON-String → PHP-Wert) beschreibt json_decode().

Syntax

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

Die Funktion gibt bei Erfolg einen JSON-kodierten string zurück, oder false bei einem Fehler (zum Beispiel wenn die Eingabe fehlerhaftes UTF-8 enthält).

Parameter

• $value — der zu kodierende Wert. Er kann jeden Typ haben, außer einem resource. Alle string-Daten müssen gültiges UTF-8 sein.
• $flags (optional) — eine Bitmaske, die die Ausgabe anpasst. Die häufigsten:
  • JSON_PRETTY_PRINT — fügt Leerzeichen und Einrückungen hinzu, sodass die Ausgabe lesbar ist.
  • JSON_UNESCAPED_UNICODE — behält Mehrbyte-Zeichen (é, ñ, 日) als Literale statt sie zu \uXXXX zu escapen.
  • JSON_UNESCAPED_SLASHES — lässt / unescaped (PHP escaped es standardmäßig als \/).
  • JSON_FORCE_OBJECT — kodiert ein sequenzielles Array als JSON-Objekt ({}) statt als Array ([]).
  • JSON_THROW_ON_ERROR — wirft bei einem Fehler eine JsonException statt false zurückzugeben (PHP 7.3+).
  • Mehrere Flags werden mit dem bitweisen OR-Operator kombiniert: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.
• $depth (optional) — die maximale Verschachtelungstiefe. Muss größer als 0 sein. Der Standardwert von 512 ist für normale Daten ausreichend.

PHP-Typen und ihre JSON-Entsprechungen

Beispiele

Ein Array kodieren

Ein assoziatives PHP-Array wird zu einem JSON-Objekt; die Schlüssel werden zu Eigenschaftsnamen.

Ausgabe:

{"a":1,"b":2,"c":3,"d":4,"e":5}

Ein Objekt kodieren

Öffentliche Eigenschaften eines Objekts werden kodiert; private und protected Eigenschaften werden übersprungen.

Ausgabe:

{"name":"John Doe","age":35,"city":"New York"}

Formatierte Ausgabe und unescaptes Unicode

Standardmäßig ist die Ausgabe kompakt, einzeilig und Nicht-ASCII-Zeichen werden escaped (so wird é zu é). Zwei Flags machen die Ausgabe menschenlesbar:

<?php

$data = [
    "name"  => "Café",
    "tags"  => ["php", "json"],
    "price" => 9.50,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

?>

Ausgabe:

{
    "name": "Café",
    "tags": [
        "php",
        "json"
    ],
    "price": 9.5
}

Beachten Sie, dass 9.50 als 9.5 ausgegeben wird — abschließende Nullen bei Fließkommazahlen werden weggelassen. Verwenden Sie JSON_PRESERVE_ZERO_FRACTION, wenn 9.0 als float erhalten bleiben soll statt zu 9 zu werden.

Fehlerbehandlung

Wenn json_encode() false zurückgibt, ist etwas schiefgelaufen — meistens fehlerhaftes UTF-8 in einem string. Überprüfen Sie json_last_error_msg(), oder übergeben Sie JSON_THROW_ON_ERROR, um stattdessen eine Exception zu erhalten.

<?php

$value = json_encode("\xB1\x31"); // invalid UTF-8 byte sequence

if ($value === false) {
    echo "Encoding failed: " . json_last_error_msg();
}

?>

Ausgabe:

Encoding failed: Malformed UTF-8 characters, possibly incorrectly encoded

Häufige Anwendungsfälle

• Daten von einer API zurückgeben. Header setzen und das kodierte Array ausgeben:

  header('Content-Type: application/json');
  echo json_encode(['status' => 'ok', 'items' => $items]);

  Kopieren

• Strukturierte Daten speichern in einer Datei oder einer Datenbank-Textspalte statt serialize(). JSON ist sprachübergreifend portabel; serialize() ist PHP-spezifisch.

• Daten an JavaScript übergeben, das auf der Seite gerendert wird, da gültiges JSON gültige JavaScript-Objektsyntax ist.

Fazit

json_encode() verwandelt PHP-Arrays und -Objekte in einen kompakten, portablen JSON-string. Greifen Sie auf JSON_PRETTY_PRINT und JSON_UNESCAPED_UNICODE zurück, wenn ein Mensch die Ausgabe lesen soll, prüfen Sie den Rückgabewert oder verwenden Sie JSON_THROW_ON_ERROR zum Schutz vor fehlerhafter Eingabe, und denken Sie daran, dass nur öffentliche Objekteigenschaften kodiert werden. Um JSON zurück in PHP zu parsen, verwenden Sie json_decode(); für eine umfassendere Übersicht siehe Mit JSON in PHP arbeiten.

Übungen