PHP json_encode(): Arrays und Objekte in JSON umwandeln

Q: Wie wandle ich in PHP ein Array in JSON um?

Übergib es an jsonencode(): jsonencode(['name' => 'Ada', 'age' => 36]) liefert {"name":"Ada","age":36}. Ein Array mit den Schlüsseln 0, 1, 2... in Reihenfolge wird stattdessen zu einem JSON-Array: json_encode(['a', 'b']) liefert ["a","b"].

Q: Wie gebe ich JSON in PHP formatiert aus?

Füge das Flag JSONPRETTYPRINT hinzu: jsonencode($data, JSONPRETTYPRINT) rückt mit 4 Leerzeichen ein und setzt jeden Wert in eine eigene Zeile. Flags kombinierst du mit |, zum Beispiel JSONPRETTYPRINT | JSONUNESCAPED_UNICODE.

Q: Warum macht json_encode aus Umlauten oder japanischem Text \u-Codes?

Standardmäßig wird jedes Nicht-ASCII-Zeichen als Escape \uXXXX geschrieben, also wird りんご zu \u308a\u3093\u3054. Das ist weiterhin gültiges JSON, aber übergib JSONUNESCAPEDUNICODE, damit die Zeichen lesbar bleiben.

Q: Wie bringe ich json_encode dazu, für ein leeres Array {} statt [] auszugeben?

Ein leeres PHP-Array wird immer als [] kodiert. Verwende new stdClass() oder (object) [] für ein leeres Objekt oder das Flag JSONFORCEOBJECT, das jedes Array im Wert zu einem Objekt macht.

json_encode($value) liefert den JSON-Text für einen PHP-Wert. Ein assoziatives Array wird zu einem JSON-Objekt, eine Liste (Schlüssel 0, 1, 2...) zu einem JSON-Array, und Strings, Zahlen, true, false und null werden zu ihren JSON-Entsprechungen.

<?php
$user = [
    'name'    => 'Ada',
    'age'     => 36,
    'langs'   => ['php', 'js'],
    'admin'   => true,
    'manager' => null,
];

$json = json_encode($user);
echo $json, "\n";
echo gettype($json), "\n";

Ausgabe:

{"name":"Ada","age":36,"langs":["php","js"],"admin":true,"manager":null}
string

Das Ergebnis ist ein einfacher String, bereit, an einen Browser geschickt, in einer Datei oder Datenbankspalte gespeichert oder an ein anderes Programm übergeben zu werden. Um JSON wieder in PHP umzuwandeln, verwendest du json_decode().

JSON formatiert ausgeben

json_encode() nimmt Flags als zweites Argument. JSON_PRETTY_PRINT fügt Zeilenumbrüche und eine Einrückung mit 4 Leerzeichen hinzu, genau das, was du in einer Konfigurationsdatei oder einem Debug-Log willst. Mehrere Flags kombinierst du mit |:

<?php
$config = [
    'app'   => 'shop',
    'debug' => false,
    'db'    => ['host' => 'localhost', 'port' => 3306],
    'tags'  => [],
];

echo json_encode($config, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";

Ausgabe:

{
    "app": "shop",
    "debug": false,
    "db": {
        "host": "localhost",
        "port": 3306
    },
    "tags": []
}

Japanischen und anderen UTF-8-Text lesbar halten

Standardmäßig schreibt json_encode() jedes Nicht-ASCII-Zeichen als Escape \u und setzt vor jeden / einen Backslash. Beides ist gültiges JSON und wird wieder zum selben Text dekodiert, macht die Ausgabe aber schwer lesbar und länger. JSON_UNESCAPED_UNICODE behält die Zeichen, und JSON_UNESCAPED_SLASHES lässt URLs, wie sie sind:

<?php
$item = ['name' => 'りんご', 'price' => 120, 'url' => 'https://example.com/fruit/apple'];

echo json_encode($item), "\n";
echo json_encode($item, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

Ausgabe:

{"name":"\u308a\u3093\u3054","price":120,"url":"https:\/\/example.com\/fruit\/apple"}
{"name":"りんご","price":120,"url":"https://example.com/fruit/apple"}

Wenn japanischer Text oder Umlaute nach dem Dekodieren verstümmelt aussehen, liegt das Problem nicht an den Escapes: Der String war von Anfang an kein UTF-8. json_encode() akzeptiert nur UTF-8 und liefert für alles andere false, wie im Abschnitt zu Fehlern gezeigt.

Wann ein Array zum Objekt statt zur Liste wird

Ein PHP-Array wird nur dann als JSON-Array kodiert, wenn seine Schlüssel genau 0, 1, 2... in Reihenfolge sind. Alle anderen Schlüssel machen es zu einem JSON-Objekt. Das erwischt viele nach unset() oder array_filter(), die Lücken in den Schlüsseln hinterlassen:

<?php
$fruits = ['apple', 'banana', 'cherry'];
unset($fruits[1]);

echo json_encode($fruits), "\n";                // keys 0, 2: an object
echo json_encode(array_values($fruits)), "\n";  // renumbered: a list

echo json_encode([1 => 'a', 2 => 'b']), "\n";   // does not start at 0

echo json_encode([]), "\n";                     // empty array: always []
echo json_encode(new stdClass()), "\n";         // empty object
echo json_encode(['a', 'b'], JSON_FORCE_OBJECT), "\n";

Ausgabe:

{"0":"apple","2":"cherry"}
["apple","cherry"]
{"1":"a","2":"b"}
[]
{}
{"0":"a","1":"b"}

Rufe vor dem Kodieren array_values() auf, wann immer der empfangende Code eine Liste erwartet. Erwartet er ein Objekt, das leer sein kann, verwendest du new stdClass() oder (object) $array, damit ein leerer Wert trotzdem als {} herauskommt.

Ein Objekt kodieren und sein JSON mit JsonSerializable steuern

Ein einfaches Objekt wird nur mit seinen öffentlichen Eigenschaften kodiert; geschützte und private werden übersprungen. Um genau zu bestimmen, wie ein Objekt in JSON aussieht, implementierst du das Interface JsonSerializable und lieferst die Daten aus jsonSerialize() zurück:

<?php
class User
{
    public string $name = 'Ada';
    public ?string $nick = null;
    private string $password = 'secret';   // never encoded
}

echo json_encode(new User()), "\n";

// A date object encodes its internals, which is rarely what an API wants
echo json_encode(new DateTimeImmutable('2026-03-14 09:30')), "\n";

class Order implements JsonSerializable
{
    public function __construct(
        private int $id,
        private float $total,
        private DateTimeImmutable $created,
    ) {}

    public function jsonSerialize(): array
    {
        return [
            'id'      => $this->id,
            'total'   => $this->total,
            'created' => $this->created->format(DATE_ATOM),
        ];
    }
}

$order = new Order(7, 19.5, new DateTimeImmutable('2026-03-14 09:30'));
echo json_encode($order, JSON_PRETTY_PRINT), "\n";

Ausgabe:

{"name":"Ada","nick":null}
{"date":"2026-03-14 09:30:00.000000","timezone_type":3,"timezone":"UTC"}
{
    "id": 7,
    "total": 19.5,
    "created": "2026-03-14T09:30:00+00:00"
}

Ein Backed Enum wie enum Status: string wird als sein Wert kodiert ("active"). Ein Pure Enum hat keinen Wert, also scheitert json_encode() daran mit „Non-backed enums have no default serialization“.

Zahlen, Floats und numerische Strings

Ganzzahlen und Floats werden als JSON-Zahlen geschrieben, und Strings bleiben Strings, auch wenn sie Ziffern enthalten. Drei Flags ändern das:

<?php
echo json_encode(['price' => 10.0]), "\n";                               // 10.0 loses its .0
echo json_encode(['price' => 10.0], JSON_PRESERVE_ZERO_FRACTION), "\n";
echo json_encode(0.1 + 0.2), "\n";                                       // full float precision

echo json_encode(['qty' => '3', 'id' => '007']), "\n";
echo json_encode(['qty' => '3', 'id' => '007'], JSON_NUMERIC_CHECK), "\n";

Ausgabe:

{"price":10}
{"price":10.0}
0.30000000000000004
{"qty":"3","id":"007"}
{"qty":3,"id":7}

JSON_NUMERIC_CHECK wandelt jeden numerischen String um, also verliert eine ID wie "007" oder eine Postleitzahl wie "01234" ihre führenden Nullen. Wandle die gemeinten Felder lieber mit (int) um, statt es auf ein ganzes Array anzuwenden.

json_encode liefert false: den Fehler finden

json_encode() liefert false, wenn es den Wert nicht kodieren kann. Die üblichen Ursachen sind ein String, der kein gültiges UTF-8 ist (Text aus einer alten Datei oder einer Latin-1-Datenbank), und die Float-Werte NAN und INF. json_last_error_msg() sagt, was schiefgelaufen ist; JSON_THROW_ON_ERROR lässt es stattdessen eine JsonException werfen:

<?php
$name = "Caf\xE9";   // "Café" in Latin-1, not valid UTF-8

var_dump(json_encode(['name' => $name]));
echo json_last_error_msg(), "\n";

// Replace the broken bytes instead of failing
echo json_encode(['name' => $name], JSON_INVALID_UTF8_SUBSTITUTE), "\n";

// Or convert the text to UTF-8 first
echo json_encode(['name' => mb_convert_encoding($name, 'UTF-8', 'ISO-8859-1')], JSON_UNESCAPED_UNICODE), "\n";

try {
    json_encode(NAN, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

Ausgabe:

bool(false)
Malformed UTF-8 characters, possibly incorrectly encoded
{"name":"Caf\ufffd"}
{"name":"Café"}
JsonException: Inf and NaN cannot be JSON encoded

JSON_THROW_ON_ERROR ist in neuem Code der bessere Standard: Ein false, das niemand prüft, wird am Ende als leerer String gespeichert oder verschickt.

JSON aus einer PHP-API zurückgeben

Ein PHP-Skript, das mit JSON antwortet, setzt den Header Content-Type, bevor es irgendetwas ausgibt, kodiert einmal und hört auf:

<?php
header('Content-Type: application/json; charset=utf-8');

$products = [
    ['id' => 1, 'name' => 'りんご', 'price' => 120],
    ['id' => 2, 'name' => 'みかん', 'price' => 80],
];

echo json_encode(['data' => $products], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
exit;

Wenn du JSON stattdessen in einem HTML-Tag <script> ausgibst, fügst du JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT hinzu. Das standardmäßige Escapen von Slashes macht aus </script> zwar <\/script>, aber dieser Schutz ist weg, sobald jemand JSON_UNESCAPED_SLASHES hinzufügt, und ein <!-- in einem Wert ändert trotzdem, wie der Browser das Skript parst. Die Flags schreiben <, >, &, ' und " als \u003C, \u003E, \u0026, \u0027 und \u0022, die JavaScript wieder als dieselben Zeichen liest.

Häufig gestellte Fragen

Wie wandle ich in PHP ein Array in JSON um?

Übergib es an json_encode(): json_encode(['name' => 'Ada', 'age' => 36]) liefert {"name":"Ada","age":36}. Ein Array mit den Schlüsseln 0, 1, 2... in Reihenfolge wird stattdessen zu einem JSON-Array: json_encode(['a', 'b']) liefert ["a","b"].

Wie gebe ich JSON in PHP formatiert aus?

Füge das Flag JSON_PRETTY_PRINT hinzu: json_encode($data, JSON_PRETTY_PRINT) rückt mit 4 Leerzeichen ein und setzt jeden Wert in eine eigene Zeile. Flags kombinierst du mit |, zum Beispiel JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.

Warum macht json_encode aus Umlauten oder japanischem Text \u-Codes?

Standardmäßig wird jedes Nicht-ASCII-Zeichen als Escape \uXXXX geschrieben, also wird りんご zu \u308a\u3093\u3054. Das ist weiterhin gültiges JSON, aber übergib JSON_UNESCAPED_UNICODE, damit die Zeichen lesbar bleiben.

Warum liefert json_encode false?

Meist, weil ein String kein gültiges UTF-8 ist oder die Daten NAN oder INF enthalten. Rufe json_last_error_msg() auf, um den Grund zu sehen, oder übergib JSON_THROW_ON_ERROR, damit es eine JsonException wirft, statt false zu liefern.

Wie bringe ich json_encode dazu, für ein leeres Array {} statt [] auszugeben?

Ein leeres PHP-Array wird immer als [] kodiert. Verwende new stdClass() oder (object) [] für ein leeres Objekt oder das Flag JSON_FORCE_OBJECT, das jedes Array im Wert zu einem Objekt macht.

Verwandte Konzepte