JSON to PHP Converter

json_decode() in PHP: The Complete Guide

PHP has had built-in JSON support since PHP 5.2 through two core functions: json_encode() and json_decode(). Understanding how json_decode() maps JSON types to PHP types is fundamental for any PHP developer working with APIs, configuration, or data storage.

The function signature is:

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

The most important parameter is the second one, $associative. When false (the default), JSON objects are returned as stdClass instances. When true, JSON objects are returned as PHP associative arrays. JSON arrays are always returned as PHP indexed arrays regardless of this parameter.

Associative Arrays vs stdClass Objects

The choice between associative arrays and stdClass objects is one of the first decisions you make when working with json_decode() in PHP.

stdClass objects are accessed with the arrow operator:

$data = json_decode($json); // returns stdClass
echo $data->name;
echo $data->address->city;
foreach ($data->items as $item) {
    echo $item->price;
}

Associative arrays are accessed with bracket notation and support all PHP array functions:

$data = json_decode($json, true); // returns array
echo $data['name'];
echo $data['address']['city'];
$prices = array_column($data['items'], 'price');
$total = array_sum($prices);

For most PHP applications, associative arrays are the practical choice. They work with array_map, array_filter, array_column, and other standard PHP array functions. Framework libraries like Laravel prefer arrays. Use stdClass only when you need to interoperate with code that explicitly expects objects.

Common json_decode Errors and How to Fix Them

PHP's json_decode() returns null on failure without throwing an exception by default. This silent failure causes many hard-to-debug issues. Here are the most common errors and their solutions:

• JSON_ERROR_SYNTAX - The JSON string is malformed. Use our JSON Validator to find and fix syntax errors before decoding.
• JSON_ERROR_UTF8 - The string contains invalid UTF-8 characters. Ensure your input is properly UTF-8 encoded: mb_convert_encoding($string, 'UTF-8', 'auto').
• JSON_ERROR_DEPTH - The JSON is nested deeper than the $depth limit (default 512). Increase the depth parameter if needed.
• Returns null for valid JSON - A common cause is a BOM (Byte Order Mark) at the start of the string. Strip it with: $json = ltrim($json, "\xef\xbb\xbf").
• Null instead of false - PHP 7.1+ changed the literal JSON string "null" to decode as PHP null, which is indistinguishable from a decode error. Use json_last_error() to differentiate.

In PHP 7.3+, the cleanest approach is to always pass JSON_THROW_ON_ERROR:

try {
    $data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    // Handle the specific error
    error_log('JSON decode failed: ' . $e->getMessage());
}

PHP JSON Best Practices

Following these practices ensures reliable and maintainable JSON handling in PHP applications:

• Always use JSON_THROW_ON_ERROR in PHP 7.3+ so errors are never silently swallowed. This is the single most impactful best practice.
• Validate input before decoding when accepting JSON from external sources. Check that the content type is application/json and that the body is non-empty before calling json_decode().
• Use JSON_UNESCAPED_UNICODE with json_encode() to avoid escaping non-ASCII characters like Chinese, Arabic, or accented Latin characters into \uXXXX sequences, which doubles payload size.
• Set the Content-Type header to application/json whenever outputting JSON from a PHP script or API endpoint.
• Sanitize data before encoding - Do not put sensitive data in JSON responses without checking authorization. JSON is not encryption.
• Use typed data classes in PHP 8+ - Define classes with typed properties and use a library like symfony/serializer to deserialize JSON directly into strongly typed PHP objects instead of generic arrays.

Frequently Asked Questions

What does json_decode() return in PHP?

By default, json_decode() returns a stdClass object for JSON objects and a PHP indexed array for JSON arrays. Numbers map to int or float, strings map to string, booleans map to bool, and JSON null maps to PHP null. If the JSON string is invalid, the function returns null and sets a JSON error code retrievable via json_last_error(). Pass true as the second argument to get associative arrays instead of stdClass for all JSON objects.

What is the difference between a PHP associative array and a stdClass object from json_decode?

With the default mode, JSON objects become stdClass and properties are accessed with $obj->key. With the associative mode (json_decode($json, true)), JSON objects become PHP arrays and values are accessed with $arr['key']. Associative arrays integrate naturally with PHP's standard library functions like array_map, array_filter, array_keys, and array_column. Most PHP frameworks and codebases prefer associative arrays for their flexibility and compatibility.

How do I check for json_decode errors in PHP?

After calling json_decode(), use json_last_error() to get the error code and json_last_error_msg() for a human-readable message. Check if (json_last_error() !== JSON_ERROR_NONE) before using the decoded value. In PHP 7.3 and later, the cleanest approach is to pass JSON_THROW_ON_ERROR as the flags parameter, which causes json_decode() to throw a JsonException on failure instead of returning null silently.

What are best practices for working with JSON in PHP?

The most important practice is to use JSON_THROW_ON_ERROR in PHP 7.3+ so invalid JSON never silently returns null and corrupts your application logic. Always set Content-Type: application/json when outputting JSON. Use JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES with json_encode() to produce clean, compact output. In PHP 8.0+ with typed properties, consider using a proper deserialization library like the Symfony Serializer or JMS Serializer to map JSON directly into typed PHP objects instead of working with untyped arrays.