JSON is a lightweight text format for structured data. It is the standard way for web APIs, JavaScript front ends, and config files to exchange information, and PHP can read and write it with a handful of built-in functions.
This page explains the ideas. The JSON Functions index lists all 5 function guides.
Decoding can fail quietly.
By default json_decode() returns null for bad input instead of raising an error. Pass the JSON_THROW_ON_ERROR flag so a JsonException is thrown, or check json_last_error() right after the call.
json_validate() needs PHP 8.3 or newer.
On older versions the function does not exist. Guard it with function_exists('json_validate') or fall back to json_decode() with JSON_THROW_ON_ERROR.
Syntax
PHP Syntax
The usual round trip between PHP data and JSON text:
PHP
// 1. PHP data -> JSON string
$json = json_encode($value, $flags = 0, $depth = 512);
// 2. JSON string -> PHP data
$object = json_decode($json); // stdClass objects
$array = json_decode($json, true); // associative arrays
// 3. Throw instead of returning null / false on errors
$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
// 4. Inspect the last error (when not using JSON_THROW_ON_ERROR)
json_last_error(); // int code, JSON_ERROR_NONE (0) when fine
json_last_error_msg(); // readable message, "No error" when fine
// 5. Check validity only (PHP 8.3+)
json_validate($json); // true or false
// json_encode(): the JSON string, or false on failure
// json_decode(): the decoded value, or null on failure
Reference
Core Ideas
What to remember when you work with JSON in PHP:
Idea
Example
Remember
Encode
json_encode($data)
Returns a string, or false on failure; add JSON_PRETTY_PRINT for readable output
Decode to objects
json_decode($json)
JSON objects become stdClass; read values with ->
Decode to arrays
json_decode($json, true)
JSON objects become associative arrays; read values with ['key']
List vs object
[1, 2] vs ['a' => 1]
A sequential PHP array encodes as a JSON array, a keyed array as a JSON object, and an empty array as []
Throw on errors
JSON_THROW_ON_ERROR
Raises JsonException and leaves the global error state untouched
Error code and text
json_last_error(), json_last_error_msg()
Report only the most recent encode or decode call
Validate
json_validate($json)
PHP 8.3+; returns true or false without building the data
Unicode and slashes
JSON_UNESCAPED_UNICODE, JSON_UNESCAPED_SLASHES
Keep readable characters and URLs instead of \uXXXX and \/
Code
PHP Examples
Three short scripts that show how JSON is used in PHP. The data is made up; replace it with your own.
Example 1 — Encode and decode
Turn a PHP array into a JSON string, then read it back and pick out one value.
json_last_error() returns 4 (JSON_ERROR_SYNTAX) and json_last_error_msg() returns the text Syntax error. The extra $data === null check avoids a false alarm when the JSON really is null.
JSON_THROW_ON_ERROR turns the failure into a JsonException. The code 512 before it is the default nesting depth, which must be passed to reach the flags argument.
json_validate() only answers true or false and builds no arrays or objects, which saves memory on large payloads. It exists in PHP 8.3 and newer, so the script checks function_exists() first.
Continue
Next: PHP JSON Functions Index
After you know the encode, decode, and error flow, open the function index for all 5 guides.
JSON (JavaScript Object Notation) is a text format for structured data that almost every language and web API understands. PHP has built-in functions to convert its arrays and objects to a JSON string with json_encode() and to turn a JSON string back into PHP data with json_decode().
By default json_decode() returns objects (stdClass) for JSON objects. Pass true as the second argument, json_decode($json, true), to get associative arrays instead. Arrays are convenient with array functions and ?? defaults; objects read nicely with the -> operator. Pick one style and use it consistently.
It returns null when the JSON is invalid, when the nesting is deeper than the depth limit, or when the JSON text is literally null. Because null can also be a valid result, check json_last_error(), or better, pass the JSON_THROW_ON_ERROR flag so a JsonException is thrown on failure.
json_last_error() returns an integer error code such as JSON_ERROR_SYNTAX, and JSON_ERROR_NONE (0) when the last call worked. json_last_error_msg() returns the matching human-readable text, such as Syntax error. Both describe only the most recent json_encode() or json_decode() call.
json_validate() was added in PHP 8.3. It checks whether a string is valid JSON and returns true or false without building any arrays or objects, so it uses less memory than json_decode() for large payloads. On PHP 8.2 and earlier it does not exist; use json_decode() with JSON_THROW_ON_ERROR instead.
Practice the examples here, then open the JSON Functions index for all 5 function guides: json_decode(), json_encode(), json_last_error(), json_last_error_msg(), and json_validate().