New Features of json_decode in PHP 5.4+ Every Developer Must Know

gitbox 2025-08-26

1. JSON_BIGINT_AS_STRING Constant

Before PHP 5.4, when json_decode encountered very large integers, it would convert them to floating-point numbers, potentially causing a loss of precision. For example, if a JSON contains a very large number:

<span><span><span class="hljs-punctuation">{</span></span><span>
    </span><span><span class="hljs-attr">"big_number"</span></span><span><span class="hljs-punctuation">:</span></span> </span><span><span class="hljs-number">12345678901234567890</span></span><span>
</span><span><span class="hljs-punctuation">}</span></span><span>
</span></span>

In PHP 5.3 or earlier, calling json_decode on this number could convert it into a floating-point type, losing precision. PHP 5.4 introduced the JSON_BIGINT_AS_STRING constant. When this constant is specified, json_decode treats large integers as strings instead of converting them to floats. This avoids precision loss.

For example:

<span><span><span class="hljs-variable">$json</span></span> = </span><span><span class="hljs-string">&#039;{"big_number": 12345678901234567890}&#039;</span></span>;
</span><span><span class="hljs-variable">$data</span></span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span>(<span>$json</span>, <span>true</span>, <span>512</span>, JSON_BIGINT_AS_STRING);
<p></span>echo $data['big_number'];  // Output "12345678901234567890"<br>
</span>

This is particularly useful for applications handling finance, scientific calculations, or other fields where numeric precision is critical.

2. JSON_PRETTY_PRINT Formatting

Although the JSON_PRETTY_PRINT constant existed in PHP 5.3, its behavior changed in PHP 5.4. In PHP 5.4, JSON_PRETTY_PRINT primarily affects the output format of json_encode rather than json_decode. However, understanding this constant is still important, as it helps developers read and understand JSON structures more easily during debugging.

For example, using json_encode with the JSON_PRETTY_PRINT constant:

<span><span><span class="hljs-variable">$array</span></span> = <span>array</span>(&#039;foo&#039; => &#039;bar&#039;, &#039;baz&#039; => &#039;qux&#039;);
</span><span><span class="hljs-keyword">echo</span></span> <span><span class="hljs-title function_ invoke__">json_encode</span></span>(<span>$array</span>, JSON_PRETTY_PRINT);
</span></span>

Output:

<span><span><span class="hljs-punctuation">{</span></span>
    </span><span>"foo": "bar",
    </span><span>"baz": "qux"
</span><span><span class="hljs-punctuation">}</span></span>
</span></span>

While json_decode does not format JSON strings itself, developers can use this when encoding JSON to produce more readable output.

3. Handling Recursive Arrays and Objects

PHP 5.4 also improved json_decode’s recursive parsing. Now, if a JSON string contains nested arrays or objects, json_decode handles these recursive structures more intelligently, ensuring complex JSON data is parsed correctly. For example:

<span>$json = &#039;{"person": {"name": "John", "age": 30}, "address": {"city": "New York", "zip": "10001"}}&#039;;
<span>$data = json_decode($json, true);
<span>print_r($data);

Output:

<span>Array
(
    [person] => Array
        (
            [name] => John
            [age] => 30
        )
    [address] => Array
        (
            [city] => New York
            [zip] => 10001
        )
)
</span>

This improvement allows developers to work with nested structures directly, converting JSON data into multidimensional arrays or objects without concern for complexity.

4. Support for UTF-8 Encoded Strings

In PHP 5.4, the json_decode function improved support for UTF-8 encoded strings containing non-ASCII characters. While PHP 5.3 and earlier also supported UTF-8, PHP 5.4 added stricter validation to ensure the input is valid UTF-8. If not, it returns null.

For example:

$json = &#039;{"name": "José"}&#039;;
$data = json_decode($json, true);
<p>echo $data['name'];  // Output: "José"<br>

This ensures that developers can handle JSON data with special characters without unexpected parsing errors or encoding issues.

5. Improved Error Handling

PHP 5.4 also optimized error handling for json_decode. When parsing fails, it returns null. To get detailed error information, developers can use json_last_error(). Before PHP 5.4, error messages were limited, making it difficult to identify the problem. PHP 5.4 provides more error codes to help developers pinpoint issues accurately.

For example:

$json = &#039;{"name": "John", "age":}&#039;;  // Invalid JSON format
$data = json_decode($json);
<p>if ($data === null) {<br>
echo 'JSON decode error: ' . json_last_error_msg();  // Outputs detailed error message<br>
}<br>

This makes it easier for developers to identify and fix JSON format issues.