1. 理解 JSON POST 请求的基础
在现代 web 服务通信中，json (javascript object notation) 已成为最流行的数据交换格式之一。当客户端需要向服务器提交结构化数据时，通常会采用 http post 请求，并将数据体（body）格式化为 json。
发送 JSON POST 请求的核心在于以下两点：
- 请求体 (Request Body) 必须是有效的 JSON 字符串。
- HTTP 头中必须包含 Content-Type: application/json。 这个头告诉服务器请求体的数据类型，以便服务器能够正确解析。
2. PHP cURL 配置关键选项
PHP 的 cURL 扩展是进行 HTTP 请求的强大工具。要发送 JSON POST 请求，我们需要配置一系列 cURL 选项。
以下是配置 cURL 发送 JSON POST 请求的关键步骤和选项：
"62111111111",
"to_name" => "Mr X",
"message_template_id" => "abc123abc123",
"channel_integration_id" => "123abc123abc",
"language" => [
"code" => "id"
],
"parameters" => [
"body" => [ // 注意：这里是一个数组，包含多个对象
[
"key" => "1",
"value" => "name",
"value_text" => "Mr X"
],
[
"key" => "2",
"value" => "vehiclereg",
"value_text" => "L0001X"
],
[
"key" => "3",
"value" => "date",
"value_text" => "29 Feb 2022"
]
]
]
];
// 4. 将 PHP 数组编码为 JSON 字符串
$json_data = json_encode($data);
// 5. 配置 cURL 选项
curl_setopt_array($curl, [
CURLOPT_URL => $url, // 设置请求的 URL
CURLOPT_RETURNTRANSFER => true, // 将 cURL 执行结果以字符串返回，而不是直接输出
CURLOPT_CUSTOMREQUEST => 'POST', // 设置 HTTP 请求方法为 POST
CURLOPT_POSTFIELDS => $json_data, // 设置 POST 请求体为 JSON 字符串
CURLOPT_HTTPHEADER => [ // 设置 HTTP 请求头
'Content-Type: application/json', // 声明请求体是 JSON 格式
'Authorization: Bearer 1122334455', // 其他自定义头，例如认证令牌
'target_channel: trial'
],
CURLOPT_SSL_VERIFYHOST => 0, // 禁用 SSL 主机名验证（仅用于开发/测试，生产环境不推荐）
CURLOPT_SSL_VERIFYPEER => 0 // 禁用 SSL 证书验证（仅用于开发/测试，生产环境不推荐）
]);
// 6. 执行 cURL 请求
$response = curl_exec($curl);
// 7. 检查是否有错误发生
if (curl_errno($curl)) {
echo 'cURL 错误: ' . curl_error($curl);
} else {
// 8. 处理响应
echo "响应内容:\n";
print_r($response);
}
// 9. 关闭 cURL 会话
curl_close($curl);
?>选项说明：
立即学习“PHP免费学习笔记（深入）”；
- CURLOPT_URL: 指定请求的目标 URL。
- CURLOPT_RETURNTRANSFER: 设置为 true 时，curl_exec() 将返回请求结果的字符串，而不是直接输出。
- CURLOPT_CUSTOMREQUEST: 对于 POST 请求，通常设置为 'POST'。
- CURLOPT_POSTFIELDS: 这是发送 JSON 数据的关键。它应该被设置为一个有效的 JSON 字符串。
- CURLOPT_HTTPHEADER: 这是一个数组，用于设置请求的 HTTP 头。务必包含 'Content-Type: application/json'，否则服务器可能无法正确解析请求体。
- CURLOPT_SSL_VERIFYHOST 和 CURLOPT_SSL_VERIFYPEER: 这两个选项用于控制 SSL 证书验证。在开发和测试环境中，有时会为了方便设置为 0（禁用验证）。但在生产环境中，强烈建议启用 SSL 验证，以确保通信安全。 如果遇到 SSL 证书问题，应配置正确的证书路径，而不是禁用验证。
3. 构建正确的 JSON 数据结构与编码
发送 JSON 数据时，最常见的错误之一是 PHP 数组结构与目标 JSON 结构不匹配，或者使用了错误的编码函数。
3.1 常见的编码错误：http_build_query() vs json_encode()
在 PHP 中，将数组转换为字符串有两种常见方法：
- http_build_query(): 此函数用于将关联数组编码为 URL 查询字符串格式（例如 key1=value1&key2=value2）。它适用于 Content-Type: application/x-www-form-urlencoded 的 POST 请求。它不适用于 JSON POST 请求。
- json_encode(): 此函数用于将 PHP 值（数组、对象等）编码为 JSON 字符串。这是发送 JSON POST 请求时必须使用的函数。
错误的尝试：
// 错误示例：使用 http_build_query() CURLOPT_POSTFIELDS => http_build_query($data); // 这会导致请求体不是 JSON 格式
这种做法会导致服务器收到的是表单编码的数据，而不是 JSON，从而解析失败。
3.2 PHP 数组结构与 JSON 结构的映射
JSON 数据结构通常包含对象（对应 PHP 关联数组）和数组（对应 PHP 索引数组）。一个常见的陷阱是当 JSON 中期望一个“对象数组”时，PHP 数组的定义方式不正确。
考虑原始 JSON 中的 parameters.body 部分：
"parameters": {
"body": [ // 这是一个JSON数组，包含多个JSON对象
{ "key": "1", "value": "name", "value_text": "Mr X" },
{ "key": "2", "value": "vehiclereg", "value_text": "L0001X" },
{ "key": "3", "value": "date", "value_text": "29 Feb 2022" }
]
}如果将其错误地映射为 PHP 数组，例如：
// 错误示例：PHP 数组中键名重复，会覆盖
"parameters" => array(
"body" => array( "key" => "1", "value" => "name", "value_text" => "Mr X" ),
"body" => array( "key" => "2", "value" => "vehiclereg", "value_text" => "L0001X" ),
"body" => array( "key" => "3", "value" => "date", "value_text" => "29 Feb 2022" )
)在 PHP 中，同一个关联数组键名（"body"）如果重复定义，后面的定义会覆盖前面的。因此，最终 parameters.body 只会保留最后一个对象的数据。当 json_encode() 处理这个错误的 PHP 数组时，结果会是：
{
"parameters": {
"body": { // 变成了单个对象，而不是数组
"key": "3",
"value": "date",
"value_text": "29 Feb 2022"
}
}
}这与目标 JSON 结构不符，导致请求失败。
正确的 PHP 数组结构： 为了将 JSON 中的 body 数组正确映射到 PHP，body 键对应的值也应该是一个 PHP 索引数组，其中每个元素都是一个关联数组（对应 JSON 对象）。
$data = [
// ... 其他数据 ...
"parameters" => [
"body" => [ // 这是一个 PHP 索引数组
[ // 第一个元素（关联数组，对应 JSON 对象）
"key" => "1",
"value" => "name",
"value_text" => "Mr X"
],
[ // 第二个元素
"key" => "2",
"value" => "vehiclereg",
"value_text" => "L0001X"
],
[ // 第三个元素
"key" => "3",
"value" => "date",
"value_text" => "29 Feb 2022"
]
]
]
];这样，json_encode($data) 才能生成符合预期的 JSON 字符串。
4. 完整的 PHP cURL JSON POST 示例
结合上述所有正确的配置和数据结构，以下是一个完整的、可运行的 PHP cURL JSON POST 请求示例：
"62111111111",
"to_name" => "Mr X",
"message_template_id" => "abc123abc123",
"channel_integration_id" => "123abc123abc",
"language" => [
"code" => "id"
],
"parameters" => [
"body" => [ // 这是一个 PHP 索引数组，每个元素是一个关联数组
[
"key" => "1",
"value" => "name",
"value_text" => "Mr X"
],
[
"key" => "2",
"value" => "vehiclereg",
"value_text" => "L0001X"
],
[
"key" => "3",
"value" => "date",
"value_text" => "29 Feb 2022"
]
]
]
];
// 将 PHP 数组编码为 JSON 字符串
$json_data = json_encode($data);
// 配置 cURL 选项
curl_setopt_array($curl, [
CURLOPT_URL => 'https://chat-service.com/api/direct', // 目标 URL
CURLOPT_RETURNTRANSFER => true, // 返回响应内容
CURLOPT_CUSTOMREQUEST => 'POST', // POST 请求
CURLOPT_SSL_VERIFYHOST => 0, // 禁用 SSL 主机名验证（生产环境不推荐）
CURLOPT_SSL_VERIFYPEER => 0, // 禁用 SSL 证书验证（生产环境不推荐）
CURLOPT_POSTFIELDS => $json_data, // 设置 JSON 请求体
CURLOPT_HTTPHEADER => [ // 设置 HTTP 头
'Content-Type: application/json', // 声明请求体是 JSON
'Authorization: Bearer 1122334455', // 认证令牌
'target_channel: trial'
],
]);
// 执行 cURL 请求
$response = curl_exec($curl);
// 检查并处理错误
if (curl_errno($curl)) {
echo 'cURL 错误 (' . curl_errno($curl) . '): ' . curl_error($curl);
} else {
// 打印响应
echo "请求成功，响应内容:\n";
print_r($response);
}
// 关闭 cURL 会话
curl_close($curl);
?>5. 错误处理与最佳实践
- 检查 cURL 执行结果： 总是检查 curl_exec() 的返回值。如果返回 false，表示 cURL 执行失败。
- 获取错误信息： 使用 curl_errno($curl) 获取错误码，使用 curl_error($curl) 获取详细的错误字符串，这对于调试非常有用。
- 处理响应： 如果服务器返回的响应也是 JSON 格式，可以使用 json_decode($response, true) 将其解析为 PHP 关联数组，以便进一步处理。
- SSL 验证： 在生产环境中，请务必启用 CURLOPT_SSL_VERIFYPEER 和 CURLOPT_SSL_VERIFYHOST。如果遇到证书问题，应确保您的 PHP 环境配置了正确的 CA 证书包（通常通过 curl.cainfo 或 CURLOPT_CAINFO 指向 cacert.pem 文件）。
- 超时设置： 对于网络请求，设置超时（如 CURLOPT_CONNECTTIMEOUT 和 CURLOPT_TIMEOUT）是良好的实践，以避免请求长时间挂起。
总结
通过本教程，我们深入探讨了如何使用 PHP cURL 正确发送 JSON POST 请求。关键在于理解 JSON 结构与 PHP 数组之间的映射关系，并正确使用 json_encode() 函数将 PHP 数组转换为 JSON 字符串。同时，配置 CURLOPT_HTTPHEADER 中的 Content-Type: application/json 也是不可或缺的一步。遵循这些指导原则和最佳实践，您将能够高效、准确地实现 PHP 应用程序与各类 JSON API 的交互。
