PHP cURL 发送 JSON POST 请求深度指南-php教程-PHP中文网

PHP cURL 发送 JSON POST 请求深度指南

本教程详细介绍了如何使用 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，从而解析失败。

Find JSON Path Online

Easily find JSON paths within JSON objects using our intuitive Json Path Finder

查看详情

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 的交互。

以上就是PHP cURL 发送 JSON POST 请求深度指南的详细内容，更多请关注php中文网其它相关文章！