本文详解如何在 PHP 中正确构造并发送包含深层嵌套结构的 JSON 对象（如消息平台 API 所需），避免因误用 http_build_query() 导致数据损坏，重点演示 json_encode() + cURL 的标准实践。
本文详解如何在 php 中正确构造并发送包含深层嵌套结构的 json 对象（如消息平台 api 所需），避免因误用 `http_build_query()` 导致数据损坏，重点演示 `json_encode()` + `curl` 的标准实践。
在 PHP 中向第三方 API（如 CM.com 消息平台）提交嵌套多维 JSON 数据时，一个常见误区是将 JSON 字符串直接赋值给变量后，错误地使用 http_build_query() 处理——这会把整个 JSON 当作扁平键值对编码为 x-www-form-urlencoded 格式，彻底破坏原始嵌套结构（例如对象变字符串、数组变索引键等），最终导致 API 拒绝请求或解析失败。
✅ 正确做法是：保持数据为原生 PHP 数组（或对象），调用 json_encode() 序列化为标准 JSON 字符串，并显式设置 Content-Type: application/json 请求头。以下是完整、可运行的解决方案：
✅ 正确发送嵌套 JSON 的推荐代码
<?php
// 1. 直接以 PHP 关联数组形式定义嵌套结构（推荐：语义清晰、类型安全）
$data = [
'messages' => [
'authentication' => [
'productToken' => 'your product token'
],
'msg' => [
[
'body' => [
'type' => 'auto',
'content' => 'Fallback Text for SMS'
],
'to' => [
['number' => '00316012345678']
],
'from' => '00316098765432',
'allowedChannels' => ['WhatsApp'],
'richContent' => [
'conversation' => [
['text' => 'A text message with *bold* formatting in a speech bubble.'],
['text' => 'Another speech bubble'],
[
'media' => [
'mediaName' => 'and an image',
'mediaUri' => 'https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg',
'mimeType' => 'image/jpeg'
]
]
]
]
]
]
]
];
// 2. JSON 编码（确保 UTF-8 安全，处理特殊字符）
$json_payload = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
if ($json_payload === false) {
throw new RuntimeException('JSON 编码失败: ' . json_last_error_msg());
}
// 3. 配置 cURL 发送 application/json 请求
$url = 'https://api.cm.com/messages'; // 替换为实际 API 地址
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $json_payload, // 传递原始 JSON 字符串
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Content-Length: ' . strlen($json_payload) // 可选但推荐
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_SSL_VERIFYPEER => false // 生产环境请设为 true 并配置 CA 证书
]);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
// 4. 处理响应
if ($error) {
echo "cURL 错误: $error";
} elseif ($http_code >= 200 && $http_code < 300) {
$result = json_decode($response, true);
echo "请求成功！响应: <pre class="brush:php;toolbar:false;">" . htmlspecialchars(print_r($result, true)) . "";
} else {
echo "HTTP 错误码: $http_code，响应: " . htmlspecialchars($response);
}
?>⚠️ 关键注意事项
- ❌ 禁止使用 http_build_query($array)：它专用于 application/x-www-form-urlencoded，会将 ['msg' => [['to' => [['number' => '...']]]]] 错误转为 msg[0][to][0][number]=...，API 无法识别。
- ✅ 必须设置 Content-Type: application/json：这是服务端正确解析 JSON 的前提，缺失该头可能导致 415 Unsupported Media Type 错误。
- ✅ 使用 json_encode() 而非手动拼接 JSON 字符串：避免引号、转义、编码问题（如中文乱码），JSON_UNESCAPED_UNICODE 保证中文不被 \uXXXX 编码。
- ✅ 始终校验 json_encode() 返回值：若输入含不可序列化类型（如资源、闭包），返回 false，需及时捕获。
- ? 调试技巧：发送前 echo $json_payload; exit; 查看实际发出的 JSON 是否符合 API 文档要求（推荐用 JSONLint 格式化验证）。
? 补充：若你只有 JSON 字符串（而非数组）
若原始数据来自文件或外部输入（如 $json_string = file_get_contents('payload.json');），应先 json_decode($json_string, true) 转为数组再编码，不要直接发送原始字符串（除非确认其已严格符合 API 要求且无额外空格/注释）：
// 安全解码 + 重编码（清理潜在格式问题）
$parsed = json_decode($json_string, true);
if ($parsed === null) {
throw new InvalidArgumentException('无效 JSON 输入: ' . json_last_error_msg());
}
$json_payload = json_encode($parsed, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);掌握这一模式，即可稳定、可靠地对接任何要求 application/json 的现代 RESTful API，彻底规避“多维 JSON 发送失败”的典型陷阱。
立即学习“PHP免费学习笔记（深入）”；
