在 PHP 项目中处理接口返回、配置文件或前端提交的数据时，JSON 往往是绕不开的数据格式。PHP 本身提供了成熟的 JSON 扩展，其中 json_decode 负责把 JSON 字符串转换为 PHP 可操作的数据结构，json_encode 负责把数组或对象转换回 JSON 字符串。理解这两个函数的参数、返回类型以及错误处理方式，基本就能完成绝大多数 JSON 解析与生成任务。
一、JSON 解析入口：json_decode 的返回类型与参数选择
PHP 解析 JSON 的核心函数是 json_decode。它接收一个符合 JSON 语法的字符串，并根据参数决定转换结果。默认情况下，JSON 中的对象会被转换为 stdClass 对象，JSON 中的数组会被转换为 PHP 数组。如果希望所有对象层级都转换为关联数组，可以把第二个参数设置为 true。
这两种返回方式并没有绝对优劣。关联数组适合统一使用数组语法处理数据，也方便和表单数据、配置项、缓存结构保持一致；对象写法在读取简单属性时更直观，适合快速访问字段。真正需要注意的是团队约定和后续处理逻辑，避免同一个 JSON 在不同模块里一会儿按数组读取，一会儿按对象读取，增加维护成本。
下面示例展示同一个 JSON 字符串分别解析为关联数组和对象的结果。为了便于查看，代码中使用 var_dump 输出结构。在实际项目中，通常会根据业务需要继续读取字段，而不是直接打印完整数据。
<?php
// 待解析的JSON字符串
$jsonStr = '{"name":"张三","age":25,"hobby":["篮球","阅读"]}';
// 解析为关联数组
$arr = json_decode($jsonStr, true);
// 解析为stdClass对象
$obj = json_decode($jsonStr);
var_dump($arr);
var_dump($obj);
?>
从运行结果可以看到，第二个参数为 true 时，最外层 JSON 对象以及内部嵌套对象都会变成关联数组。不传第二个参数时，最外层是对象，内部的 hobby 字段仍然保留为 PHP 数组，因为它在 JSON 中本来就是数组类型。
二、解析结果的访问方式：数组、对象与嵌套结构
解析 JSON 之后，下一步就是访问其中的字段。若解析结果是关联数组，可以使用键名取值；若解析结果是对象，可以使用对象属性语法取值。对于嵌套结构，只需要按照层级逐层向下访问即可，这和读取普通 PHP 数组或对象没有本质区别。
实际开发中更常见的是多层嵌套的 JSON，例如接口返回中包含状态码、提示信息、用户信息、订单列表等结构。面对这类数据，建议先明确最外层结构，再确认 data 字段是对象还是数组，最后处理列表字段。对于列表字段，通常结合 foreach 遍历，可以减少手动取下标带来的错误。
下面的代码先演示基础字段读取，再演示复杂嵌套 JSON 的访问方式。示例中的 JSON 包含用户信息、订单列表和状态码，比较接近日常接口返回的数据形态。
<?php
$jsonStr = '{"name":"张三","age":25,"hobby":["篮球","阅读"]}';
// 按关联数组访问
$arr = json_decode($jsonStr, true);
echo $arr['name'];
echo $arr['age'];
echo $arr['hobby'][0];
// 按对象访问
$obj = json_decode($jsonStr);
echo $obj->name;
echo $obj->age;
echo $obj->hobby[0];
?>
<?php
$complexJson = '{"code":200,"msg":"请求成功","data":{"user_id":1001,"user_info":{"name":"王五","address":"北京市朝阳区"},"order_list":[{"order_id":1,"price":199},{"order_id":2,"price":299}]}}';
$arr = json_decode($complexJson, true);
// 访问嵌套用户信息
echo $arr['data']['user_info']['name'];
// 访问第一个订单价格
echo $arr['data']['order_list'][0]['price'];
// 遍历订单列表
foreach ($arr['data']['order_list'] as $order) {
echo $order['order_id'] . ':' . $order['price'] . PHP_EOL;
}
?>
在读取嵌套字段时，如果字段可能不存在，建议先判断或使用空合并运算符等方式做兜底，避免因为某个字段缺失导致程序报错。对于接口数据尤其如此，因为外部系统返回的字段可能随版本变化，不能默认所有字段始终存在。
三、解析失败与边界情况：错误码、空值与常见非法格式
JSON 解析并不总是成功。当字符串不符合 JSON 语法时，json_decode 会解析失败。此时不能只简单判断返回值是否为 null，因为 JSON 字符串本身也可能合法地表示 null。更稳妥的方式是结合 json_last_error 或 json_last_error_msg 判断最近一次解析是否出现错误。
常见的非法 JSON 包括键名没有使用双引号、字符串使用单引号、末尾多逗号、包含未转义的控制字符、编码不是 UTF-8 等。这些问题在手动拼接 JSON 或从第三方接口获取数据时比较常见。对于由 PHP 生成 JSON 的场景，建议始终使用 json_encode，不要手动拼接字符串，这样可以显著降低语法错误风险。
| 函数 | 作用 |
|---|---|
json_last_error | 返回最近一次 JSON 操作的错误码 |
json_last_error_msg | 返回最近一次 JSON 操作的错误信息 |
下面的示例展示了一个非法 JSON 字符串的处理方式。由于 age 字段没有使用双引号包裹，解析会失败，程序通过错误码和错误信息定位问题。
<?php
$invalidJson = '{"name":"张三",age:25}';
$result = json_decode($invalidJson, true);
if (json_last_error() !== JSON_ERROR_NONE) {
$errorCode = json_last_error();
$errorMsg = json_last_error_msg();
echo 'JSON解析失败，错误码：' . $errorCode . '，错误信息：' . $errorMsg;
} else {
echo 'JSON解析成功';
}
?>
在封装公共方法时，可以把错误判断放到解析函数内部，让调用方只关心成功时的数据结构或失败时的统一返回值。这样可以让业务代码更简洁，也方便统一记录日志、返回接口错误码或进行重试。
四、生成 JSON：json_encode 的常用选项与输出质量
除了解析外部 JSON，PHP 也经常需要把数组或对象转换成 JSON 返回给前端、写入日志、推送给消息队列或保存到缓存中。这个转换过程由 json_encode 完成。它接受 PHP 数据，并返回 JSON 字符串。如果转换失败，会返回 false，因此必要时应检查返回值。
在中文项目中，经常需要关注 JSON_UNESCAPED_UNICODE 选项。默认情况下，中文可能被转义为 Unicode 序列，虽然这仍然是合法 JSON，解析时也能还原，但可读性会下降。如果希望输出更直观，可以加上该选项。若输出中包含斜杠，也可以使用 JSON_UNESCAPED_SLASHES 让 URL 更易读。
下面示例将一个包含中文、数字、小数和数组的用户数据转换为 JSON 字符串，并使用 JSON_UNESCAPED_UNICODE 保证中文直接输出。
<?php
$user = [
'name' => '李四',
'age' => 28,
'score' => 95.5,
'tags' => ['开发', '测试']
];
$jsonStr = json_encode($user, JSON_UNESCAPED_UNICODE);
echo $jsonStr;
?>
需要注意的是，JSON 对数据类型有明确约束。PHP 数组如果键名不是连续数字，会被编码为对象；如果是连续数字键，则会被编码为数组。若接口要求某些字段必须输出为对象，可能需要使用对象或空数组的特殊处理方式，避免因数据结构差异导致前端解析异常。
五、实战组合：从原始字符串到安全输出
真实项目中的 JSON 处理往往不是单行函数调用，而是一个完整流程：拿到原始字符串，做必要清理，解析为数组，判断错误，再按业务规则读取字段。对于接口返回，通常还会先判断 HTTP 状态、响应头或业务 code 字段，然后才进入数据解析阶段。
如果项目中有多个地方需要解析 JSON，可以封装一个简单函数，统一处理空字符串、非法 JSON 和返回类型。这样调用方不需要重复写 json_decode 和 json_last_error，也能保证返回结构一致。下面示例把解析逻辑封装为函数，并继续处理嵌套数据与订单列表。
<?php
function parseJsonToArray($json) {
if (!is_string($json) || trim($json) === '') {
return null;
}
$data = json_decode($json, true);
if (json_last_error() !== JSON_ERROR_NONE || !is_array($data)) {
return null;
}
return $data;
}
$raw = '{"code":200,"msg":"请求成功","data":{"user_id":1001,"user_info":{"name":"王五"},"order_list":[{"order_id":1,"price":199},{"order_id":2,"price":299}]}}';
$data = parseJsonToArray($raw);
if ($data === null) {
echo 'JSON解析失败';
} else {
echo $data['data']['user_info']['name'] ?? '';
foreach ($data['data']['order_list'] ?? [] as $order) {
echo $order['order_id'] . ':' . $order['price'] . PHP_EOL;
}
}
?>
这种写法的重点不是代码行数，而是边界处理。原始输入可能为空，解析可能失败，字段可能缺失，列表可能不存在。通过函数封装和兜底取值，可以让后续业务逻辑更加稳定。对于需要记录日志的系统，还可以在函数内部记录错误信息和原始响应片段，方便排查问题。
六、总结与要点回顾
PHP 解析 JSON 的主线非常清晰：使用 json_decode 将字符串转换为数组或对象，使用 json_encode 将 PHP 数据转换为 JSON 字符串，并通过错误处理函数判断解析是否成功。掌握这条主线后，再结合嵌套结构访问、字段兜底和编码选项，就能应对大多数接口对接和数据处理场景。
在实际项目中，建议优先选择统一的返回类型，尽量使用关联数组或统一的数据传输对象；不要手动拼接 JSON，避免语法错误；解析外部数据时始终考虑失败情况；输出中文时根据可读性需求选择合适选项。把这些细节处理好，JSON 数据交换会变得更加稳定，也更容易维护。
PHPJSON解析json_decodejson_encode数组操作修改时间：2026-06-29 10:33:25