Skip to content
Tutorials Center
My learning

Topics

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.

PHP
try {
    $data = json_decode($text, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo $e->getMessage();
}

Try it

PHP The global error state

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.

PHP Exceptions and partial output

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

PHP
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 inside echo arguments).
  • JSON_THROW_ON_ERROR neither 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 the JSON_ERROR_* value, so $e->getCode() === JSON_ERROR_UTF8 works.
  • Partial output is a last resort. JSON_PARTIAL_OUTPUT_ON_ERROR hides data loss; use it for logging, not for data you send to clients.
  • Cleaning input: repair text with mb_convert_encoding(), or JSON_INVALID_UTF8_SUBSTITUTE, when the source may contain broken UTF-8.
  • Depth errors protect you from hostile input: pass a small $depth when you know your data is shallow.
  • Messages are English and not meant for end users; log them and show a generic message.