PHP Reference ยท Functions and Classes
PHP JSON errors and flags
Reference for PHP JSON error handling: JSON_THROW_ON_ERROR, json_last_error(), json_last_error_msg(), the JSON_ERROR_* constants and encode/decode flags.
PHP's JSON functions can fail in two styles. The old style stores the problem in a global error state: json_encode() returns false, json_decode() returns null, and you must call json_last_error() or json_last_error_msg() to find out why. The modern style, available since PHP 7.3, passes JSON_THROW_ON_ERROR and receives a JsonException.
Prefer the exception style. It cannot be forgotten, it does not depend on global state that the next JSON call overwrites, and it removes the ambiguity of json_decode() returning null for both failure and the valid input null.
try { $data = json_decode($text, true, 512, JSON_THROW_ON_ERROR); } catch (JsonException $e) { echo $e->getMessage(); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
json_last_error(): int json_last_error_msg(): string
Return value: json_last_error() returns the code of the error from the last JSON encode or decode call in the current context (JSON_ERROR_NONE, which is 0, when it succeeded). json_last_error_msg() returns the matching English text, such as "Syntax error".
| Constant | Meaning |
|---|---|
JSON_ERROR_NONE |
No error. |
JSON_ERROR_DEPTH |
The nesting depth limit was exceeded. |
JSON_ERROR_STATE_MISMATCH |
Underflow or mismatched brackets. |
JSON_ERROR_CTRL_CHAR |
An unexpected control character was found. |
JSON_ERROR_SYNTAX |
Malformed JSON. |
JSON_ERROR_UTF8 |
Malformed UTF-8 in a string. |
JSON_ERROR_RECURSION |
The value being encoded refers to itself. |
JSON_ERROR_INF_OR_NAN |
NAN or INF cannot be encoded. |
JSON_ERROR_UNSUPPORTED_TYPE |
A resource or other unsupported value. |
JSON_ERROR_INVALID_PROPERTY_NAME |
A property name cannot be used when decoding to an object. |
JSON_ERROR_UTF16 |
A bad Unicode escape sequence in a string. |
Flags related to errors: JSON_THROW_ON_ERROR (throw JsonException, with the error code as the exception code), JSON_PARTIAL_OUTPUT_ON_ERROR (encode: replace unencodable values with null and continue), JSON_INVALID_UTF8_IGNORE (drop invalid bytes) and JSON_INVALID_UTF8_SUBSTITUTE (replace them with U+FFFD).
Usage notes
- The global state is overwritten by every call that does not use
JSON_THROW_ON_ERROR. Read it immediately after the call you care about, before any other JSON function (even one insideechoarguments). JSON_THROW_ON_ERRORneither reads nor resets it. The second example shows that a throwing-mode call leaves an earlier error in place, so mixing the two styles confuses readers. Choose one style per project.- Exception code:
$e->getCode()equals theJSON_ERROR_*value, so$e->getCode() === JSON_ERROR_UTF8works. - Partial output is a last resort.
JSON_PARTIAL_OUTPUT_ON_ERRORhides data loss; use it for logging, not for data you send to clients. - Cleaning input: repair text with
mb_convert_encoding(), orJSON_INVALID_UTF8_SUBSTITUTE, when the source may contain broken UTF-8. - Depth errors protect you from hostile input: pass a small
$depthwhen you know your data is shallow. - Messages are English and not meant for end users; log them and show a generic message.