Understanding the json_decode Function in PHP

The json_decode function in PHP turns a JSON-formatted string into a native PHP value you can read and manipulate. It is the counterpart to json_encode, which goes the other way (PHP value → JSON string). You reach for json_decode whenever data arrives as text and you need to work with it: a REST API response, a webhook payload, a config file, or a column stored in a database.

This chapter covers the function's signature, the difference between decoding to an object and to an associative array, how nested data behaves, depth and flag options, and the right way to handle invalid input.

What is JSON?

JSON (JavaScript Object Notation) is a lightweight, text-based data-interchange format that is easy for humans to read and for machines to parse. It represents data as key-value pairs (objects, written {}) and ordered lists (arrays, written []), with strings, numbers, booleans, and null as scalar values. Because almost every language can produce and consume it, JSON has become the default format for web APIs. See the PHP and JSON overview for the bigger picture.

Syntax

json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed

The function returns the decoded value (array, stdClass, string, int, float, bool, or null), or null on failure.

Decoding a JSON string

The most common use is decoding a JSON object. Pass true as the second argument to get a PHP associative array back.

PHP json_decode function example

Here $json represents a person's name, age, and city. With true, json_decode builds a PHP array, so the result is:

Array
(
    [name] => John
    [age] => 30
    [city] => New York
)

You then read values with array syntax, e.g. $array['name']. See associative arrays for more on this data structure.

Using the Second Parameter

The second parameter of the json_decode function is optional, but it is often used to control the type of the returned variable. If the second parameter is set to true, json_decode will return an array. If the second parameter is set to false (the default), json_decode will return an object.

PHP json_decode function example with objects

When $associative is false (or omitted), json_decode returns a stdClass object. You read values with the object property syntax $object->name, $object->age, and so on. Use this form when you prefer object-style access or when the result will be passed to code that expects objects (see PHP classes and objects).

Decoding nested JSON

Real-world JSON is usually nested. json_decode handles nesting automatically: each level becomes a nested array (with true) or a nested object (with false).

<?php

$json = '{"user":{"name":"John","roles":["admin","editor"]}}';
$data = json_decode($json, true);

echo $data['user']['name'];      // John
echo "\n";
echo $data['user']['roles'][0];  // admin

?>

Inner JSON objects become inner arrays, and JSON arrays ([...]) become PHP indexed arrays you can loop over with foreach.

Error Handling

If the input string passed to json_decode is not valid JSON, the function returns null. However, null is also a valid JSON value, so checking if ($array === null) cannot distinguish between a decoding error and a successful decode of the literal null. To properly handle errors, check json_last_error() or use the JSON_THROW_ON_ERROR flag (PHP 7.3+).

PHP handle json_decode errors

The string above is missing a closing quote, so json_last_error() is not JSON_ERROR_NONE and the message explains what went wrong.

From PHP 7.3 onwards, the cleaner option is the JSON_THROW_ON_ERROR flag, which throws a JsonException instead of silently returning null:

<?php

try {
    $data = json_decode('{"invalid": }', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "Could not decode JSON: " . $e->getMessage();
}

?>

This lets you handle malformed input with standard try/catch blocks instead of checking the result by hand after every call.

Related functions

• json_encode — convert a PHP value into a JSON string.
• PHP and JSON — overview of working with JSON in PHP.
• PHP JSON reference — full list of PHP's JSON functions and constants.

Conclusion

The json_decode function in PHP is a powerful tool for working with JSON data. It is fast, reliable, and easy to use. By understanding the details of json_decode and its second parameter, you can decode JSON strings with confidence and use the resulting data in your PHP applications.

Practice