Signatur
Beschreibung
JsonException erweitert RuntimeException und wird geworfen, sobald json_encode() oder json_decode() einen Fehler erkennen und das Flag JSON_THROW_ON_ERROR gesetzt ist. Ohne dieses Flag geben beide Funktionen bei Fehlern lediglich false bzw. null zurück und setzen intern einen Fehlercode, der nur über json_last_error() abgerufen werden kann.
Der Vorteil der Exception-basierten Fehlerbehandlung ist, dass Fehler nicht mehr manuell nach jedem JSON-Aufruf geprüft werden müssen. Stattdessen kann ein einziger try/catch-Block den gesamten Verarbeitungsblock absichern, was den Code übersichtlicher und robuster macht.
Die Methode getMessage() liefert eine lesbare Fehlerbeschreibung (z. B. "Syntax error"), während getCode() den JSON-Fehlercode zurückgibt, der den bekannten Konstanten wie JSON_ERROR_SYNTAX entspricht.
JsonException hat selbst keine eigenen Methoden oder Properties — sie erbt alles von RuntimeException und damit von Exception. Es lohnt sich, sie in modernem Code grundsätzlich gegenüber der alten json_last_error()-Prüfung zu bevorzugen.
Beispiele
JSON dekodieren mit Fehlerbehandlung via JsonException
<?php
$invalidJson = '{name: "Alice"}';
try {
$data = json_decode($invalidJson, true, 512, JSON_THROW_ON_ERROR);
echo 'Name: ' . $data['name'];
} catch (JsonException $e) {
echo 'JSON-Fehler: ' . $e->getMessage();
echo PHP_EOL;
echo 'Fehlercode: ' . $e->getCode();
}
JSON kodieren mit Fehlerbehandlung via JsonException
<?php
// Eine Ressource kann nicht als JSON kodiert werden
$data = [
'handle' => fopen('php://memory', 'r'),
];
try {
$json = json_encode($data, JSON_THROW_ON_ERROR);
echo $json;
} catch (JsonException $e) {
echo 'Kodierungsfehler: ' . $e->getMessage();
echo PHP_EOL;
echo 'Fehlercode: ' . $e->getCode();
} finally {
// Ressource schließen
fclose($data['handle']);
}
Vergleich: alte Methode vs. JsonException
<?php
$invalidJson = 'ungültig';
// Alte Methode (vor PHP 7.3)
$result = json_decode($invalidJson, true);
if (json_last_error() !== JSON_ERROR_NONE) {
echo 'Alter Weg – Fehler: ' . json_last_error_msg() . PHP_EOL;
}
// Neue Methode mit JSON_THROW_ON_ERROR
try {
$result = json_decode($invalidJson, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
echo 'Neuer Weg – Fehler: ' . $e->getMessage() . PHP_EOL;
}
// Wichtig · Fallstricke
Wichtig: JSON_THROW_ON_ERROR muss explizit als Flag übergeben werden — standardmäßig wirft weder json_encode() noch json_decode() Ausnahmen. Bestehender Code, der auf den Rückgabewert false/null oder json_last_error() prüft, bleibt davon unberührt.
Da JsonException von RuntimeException und nicht von ErrorException erbt, kann sie unabhängig von einem globalen Exception-Handler gezielt gefangen werden. Es empfiehlt sich, sie immer vor der allgemeinen \Exception im catch-Block zu platzieren.