PHP 5.4+ 中 json_decode 有哪些新特性？开发者必须知道的变化

gitbox 2025-08-26

1. JSON_BIGINT_AS_STRING 常量

在 PHP 5.4 之前，当 json_decode 遇到非常大的整数时，它会将其转换为浮动类型，这可能导致数据丢失。举个例子，假如 JSON 中有一个很大的数字：

<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><span class="hljs-number">12345678901234567890</span></span><span>
</span><span><span class="hljs-punctuation">}</span></span><span>
</span></span>

在 PHP 5.3 或更早版本中，调用 json_decode 时这个数字可能会变成浮动类型，精度会丢失。而 PHP 5.4 引入了 JSON_BIGINT_AS_STRING 常量，当你指定此常量时，json_decode 会将大整数作为字符串处理，而不是转换为浮动类型。这样就避免了精度丢失的问题。

例如：

<span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"big_number": 12345678901234567890}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>, </span><span><span class="hljs-literal">true</span></span><span>, </span><span><span class="hljs-number">512</span></span><span>, JSON_BIGINT_AS_STRING);

</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-variable">$data</span></span><span>[</span><span><span class="hljs-string">'big_number'</span></span><span>];  </span><span><span class="hljs-comment">// 输出 "12345678901234567890"</span></span><span>
</span></span>

这种方式尤其适合需要处理金融、科学计算等领域的应用，它可以确保数值的精度不受影响。

2. JSON_PRETTY_PRINT 输出格式化

虽然 JSON_PRETTY_PRINT 常量早在 PHP 5.3 中就已经存在，但其对 json_decode 函数的行为发生了变化。在 PHP 5.4 中，JSON_PRETTY_PRINT 主要影响的是 json_encode 函数的输出格式，而不再影响 json_decode。不过，了解这个常量的作用仍然是很重要的，因为它能帮助开发者在调试时更容易阅读和理解 JSON 数据的结构。

举个例子，json_encode 与 JSON_PRETTY_PRINT 常量结合使用：

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

输出结果：

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

虽然 json_decode 本身不会格式化 JSON 字符串，但开发者可以在进行 json_encode 时使用它，确保输出更友好易读。

3. 递归数组和对象的处理

PHP 5.4 还增强了 json_decode 的递归解析能力。现在，如果 JSON 字符串中包含了嵌套的数组或对象，json_decode 会更智能地处理这些递归结构，确保更复杂的 JSON 数据能够正确解析。例如：

<span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"person": {"name": "John", "age": 30}, "address": {"city": "New York", "zip": "10001"}}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>, </span><span><span class="hljs-literal">true</span></span><span>);

</span><span><span class="hljs-title function_ invoke__">print_r</span></span><span>(</span><span><span class="hljs-variable">$data</span></span><span>);
</span></span>

输出：

<span><span><span class="hljs-title function_ invoke__">Array</span></span><span>
(
    [person] =&gt; </span><span><span class="hljs-title function_ invoke__">Array</span></span><span>
        (
            [name] =&gt; John
            [age] =&gt; </span><span><span class="hljs-number">30</span></span><span>
        )
    [address] =&gt; </span><span><span class="hljs-title function_ invoke__">Array</span></span><span>
        (
            [city] =&gt; New York
            [zip] =&gt; </span><span><span class="hljs-number">10001</span></span><span>
        )
)
</span></span>

这种改进使得开发者不必担心嵌套结构的复杂性，JSON 数据可以直接转换成多维数组或对象。

4. 支持 UTF-8 编码的字符串

PHP 5.4 版本中的 json_decode 函数在处理包含非 ASCII 字符的 JSON 字符串时，增强了对 UTF-8 编码的支持。尽管在 PHP 5.3 及更早版本中，json_decode 也支持 UTF-8 编码，但 PHP 5.4 对此做了更严格的验证，确保输入数据是有效的 UTF-8 编码，否则会返回 null。

例如：

<span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"name": "José"}'</span></span><span>;
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>, </span><span><span class="hljs-literal">true</span></span><span>);

</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-variable">$data</span></span><span>[</span><span><span class="hljs-string">'name'</span></span><span>];  </span><span><span class="hljs-comment">// 输出 "José"</span></span><span>
</span></span>

这种改进确保了开发者在处理包含特殊字符的 JSON 数据时，不会出现意外的解析错误或编码问题。

5. 错误处理的改进

PHP 5.4 在 json_decode 函数的错误处理上做了一些优化。当 json_decode 解析失败时，返回 null。但要获取更详细的错误信息，可以使用 json_last_error() 函数。在 PHP 5.4 之前，错误信息较为简略，开发者可能很难确定具体的错误原因，而现在 PHP 5.4 提供了更多的错误码，能够帮助开发者更精确地定位问题。

例如：

<span><span><span class="hljs-variable">$json</span></span><span> = </span><span><span class="hljs-string">'{"name": "John", "age":}'</span></span><span>;  </span><span><span class="hljs-comment">// 错误的 JSON 格式</span></span><span>
</span><span><span class="hljs-variable">$data</span></span><span> = </span><span><span class="hljs-title function_ invoke__">json_decode</span></span><span>(</span><span><span class="hljs-variable">$json</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$data</span></span><span> === </span><span><span class="hljs-literal">null</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'JSON 解码错误: '</span></span><span> . </span><span><span class="hljs-title function_ invoke__">json_last_error_msg</span></span><span>();  </span><span><span class="hljs-comment">// 输出详细的错误信息</span></span><span>
}
</span></span>

这样，开发者可以方便地识别和修复 JSON 数据的格式问题。