In PHP, json_decode() turns a JSON string into a PHP value. Depending on the options, a JSON object becomes either a stdClass object or an associative array.
JSON is the text format most APIs use to send data. json_decode() reads that text so you can work with it as normal PHP variables. If the text is broken or too deeply nested, it returns null, or throws a JsonException when you use JSON_THROW_ON_ERROR.
Syntax
Call json_decode() with the values you need. Start with this line.
PHP
$data = json_decode($json, true);
Call
What it does
json_decode('{"a":1}')
Returns a stdClass object, so you read values with $data->a.
json_decode('{"a":1}', true)
Returns an associative array, so you read values with $data['a'].
Throws a JsonException on bad JSON instead of quietly returning null.
json_decode() returns null on failure, but null is also a valid JSON value, so check for errors with JSON_THROW_ON_ERROR or json_last_error(). Also remember that an empty string is not valid JSON.
Library declarations
PHP
json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed
Parameters
Parameter
Description
json
Required. The JSON string to decode. It must be valid UTF-8 text, and an empty string is a syntax error.
associative
Optional. When true, JSON objects become associative arrays. When false, they become stdClass objects. When null (the default), the JSON_OBJECT_AS_ARRAY flag decides.
depth
Optional. The maximum nesting depth allowed. The default is 512. It must be greater than 0, otherwise PHP throws a ValueError.
flags
Optional. A bitmask of options such as JSON_THROW_ON_ERROR, JSON_BIGINT_AS_STRING, JSON_OBJECT_AS_ARRAY and JSON_INVALID_UTF8_IGNORE. The default is 0.
Return Value
Return Value
Description
mixed
The decoded value: an object, array, string, int, float, bool or null. It returns null if the JSON is invalid or the depth limit is exceeded (unless JSON_THROW_ON_ERROR is set, in which case a JsonException is thrown).
PHP Examples
Example 1 — Objects vs Associative Arrays
Decode the same JSON twice: once into a stdClass object and once into an array using the associative argument.
NULL
Maximum stack depth exceeded
Rows: 2
First value: 1
How It Works
The JSON has two levels of nesting: an outer array that holds inner arrays.
A depth of 1 only allows one level, so decoding fails and returns null.
json_last_error_msg() reports that the maximum stack depth was exceeded.
A depth of 2 is enough, so the data decodes into a normal PHP array.
Frequently Asked Questions
It converts a JSON string into a PHP value. JSON objects become stdClass objects (or arrays if you pass true), JSON arrays become PHP arrays, and numbers, strings, booleans and null become matching PHP types.
Pass true if you prefer working with arrays, which is common for beginners and for API data. Leave it out (or pass false) if you want objects. Arrays are easier to loop over and pass to other functions.
Either the JSON text is invalid, the depth limit was exceeded, or the JSON itself was the word null. Use json_last_error() or json_last_error_msg() to find out, or use JSON_THROW_ON_ERROR to get an exception.
The modern way is to pass JSON_THROW_ON_ERROR as a flag and wrap the call in try and catch for JsonException. The older way is to call json_last_error() right after json_decode() and compare it to JSON_ERROR_NONE.
It sets how many levels of nested arrays or objects are allowed. The default is 512, which is plenty for normal data. If the JSON is nested deeper than the limit, decoding fails with a depth error.