本教程详细介绍了如何使用 PHP cURL 正确发送 JSON 格式的 POST 请求。内容涵盖了构建符合 JSON 规范的 PHP 数组、利用 json_encode() 函数将数组转换为 JSON 字符串，以及配置 cURL 选项（如 CURLOPT_POSTFIELDS 和 CURLOPT_HTTPHEADER）的关键步骤。文章还指出了常见的编码错误和数组结构陷阱，并提供了完整的示例代码，旨在帮助开发者高效、准确地实现 JSON 数据交互。
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 请求的关键步骤和选项：
<?php // 1. 初始化 cURL 会话 $curl = curl_init(); // 2. 目标 URL $url = 'https://chat-service.com/api/direct'; // 3. 构建请求数据（PHP 数组形式，稍后会详细说明） $data = [ "to_number" => "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 请求示例：
<?php $curl = curl_init(); // 构建符合 JSON 结构的 PHP 数组 $data = [ "to_number" => "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 的交互。
评论（已关闭）
评论已关闭