PHP json_decode() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
JSON

Definition

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);
CallWhat 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'].
json_decode($json, true, 512, JSON_THROW_ON_ERROR)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

ParameterDescription
jsonRequired. The JSON string to decode. It must be valid UTF-8 text, and an empty string is a syntax error.
associativeOptional. When true, JSON objects become associative arrays. When false, they become stdClass objects. When null (the default), the JSON_OBJECT_AS_ARRAY flag decides.
depthOptional. The maximum nesting depth allowed. The default is 512. It must be greater than 0, otherwise PHP throws a ValueError.
flagsOptional. 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 ValueDescription
mixedThe 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.

PHP
<?php
$json = '{"name":"Asha","age":25}';

$obj = json_decode($json);
echo $obj->name, PHP_EOL;
echo get_class($obj), PHP_EOL;

$arr = json_decode($json, true);
echo $arr['name'], PHP_EOL;
echo gettype($arr), PHP_EOL;

How It Works

  1. The first call has no second argument, so the JSON object becomes a stdClass object.
  2. With an object you read values using the arrow, like $obj->name.
  3. Passing true as the second argument turns the JSON object into an associative array.
  4. With an array you read values using brackets, like $arr['name'].

Example 2 — Catching Bad JSON with JSON_THROW_ON_ERROR

Broken JSON quietly gives null by default. Add JSON_THROW_ON_ERROR to get a JsonException you can catch.

PHP
<?php
try {
    json_decode('{"name":', false, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "Error: ", $e->getMessage(), PHP_EOL;
    echo "Code: ", $e->getCode(), PHP_EOL;
}

var_dump(json_decode('{bad json}'));
echo json_last_error_msg(), PHP_EOL;

How It Works

  1. The JSON string stops after the colon, so it is incomplete and invalid.
  2. Because JSON_THROW_ON_ERROR is set, PHP throws a JsonException instead of returning null.
  3. The exception code 4 is the same as JSON_ERROR_SYNTAX.
  4. Without the flag, json_decode() returns null and you must ask json_last_error_msg() what went wrong.

Example 3 — Depth Limits

The depth argument limits how deeply arrays and objects can be nested. This protects your script from huge or malicious input.

PHP
<?php
$json = '[[1,2],[3,4]]';

var_dump(json_decode($json, true, 1));
echo json_last_error_msg(), PHP_EOL;

$data = json_decode($json, true, 2);
echo "Rows: ", count($data), PHP_EOL;
echo "First value: ", $data[0][0], PHP_EOL;

How It Works

  1. The JSON has two levels of nesting: an outer array that holds inner arrays.
  2. A depth of 1 only allows one level, so decoding fails and returns null.
  3. json_last_error_msg() reports that the maximum stack depth was exceeded.
  4. 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.

Next: json_encode()

json_encode() converts a PHP value, such as an array or object, into a JSON string. It is .

json_encode() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful