PHP cURL发送复杂JSON数据及变量的最佳实践

DDD

发布时间：2025-10-19 12:19:15

147人浏览过

来源于php中文网

原创

PHP cURL发送复杂JSON数据及变量的最佳实践

本文旨在解决php curl在发送包含变量的复杂json数据时遇到的常见问题。核心在于避免手动拼接json字符串，而是通过构建php多维数组，并使用`json_encode()`将其转换为标准json格式，再通过`curlopt_postfields`发送。文章将提供详细的示例代码、调试技巧及注意事项，确保api请求的准确性和稳定性。

PHP cURL发送JSON数据：从字符串到结构化数组

在使用PHP cURL与RESTful API交互时，发送JSON格式的数据是一种常见需求。然而，当JSON数据结构复杂且包含动态变量时，初学者常会遇到变量无法正确解析或API返回空值的问题。这通常源于手动拼接JSON字符串时，未能正确处理引号、转义字符以及多维数组的结构。

常见问题分析

最初的代码示例中，开发者尝试通过直接将变量嵌入到硬编码的JSON字符串中来构建请求体：

curl_setopt($ch, CURLOPT_POSTFIELDS, "{\n\t\"reference\": \"my-order-ref-0001\",\n\t\"client\": {\n    \t\"cpf\": \"43164853858\",\n    \t\"name\": \"John Doe\",\n    \t\"email\": \"...\",\n    \t\"birthdate\": \"1982-01-14\",\n    \t\"cep\": \"18053190\",\n    \t\"phone\": \"15987452584\"\n\t}, ... }");

当尝试将"John Doe"替换为$clientName等变量时，API不再返回预期结果。这种方法极易出错，因为PHP变量在双引号字符串中会被解析，但如果变量值本身包含特殊字符（如引号），或者JSON结构复杂，手动拼接很难保证生成的JSON字符串是有效的。此外，对于多维数组或对象，手动拼接更是繁琐且容易出错。

解决方案：使用PHP数组构建JSON并编码

解决此问题的最佳实践是：首先在PHP中构建一个与目标JSON结构完全对应的关联数组，然后使用json_encode()函数将其转换为标准的JSON字符串。这种方法不仅避免了手动处理引号和转义字符的麻烦，还使得代码更具可读性和可维护性。

立即学习“PHP免费学习笔记（深入）”；

步骤一：构建PHP关联数组

Summarizer

基于 AI 的文本段落摘要生成器

下载

根据API文档定义的JSON结构，创建一个PHP多维关联数组。将所有动态数据作为变量插入到数组的相应位置。

function generatePayment($sendId, $clientCPF, $clientName, $clientEmail, $clientCep, $clientPhone, $amount){
    // ... 其他配置

    $postData = array(
        "reference" => "my-order-ref-0001", // 示例值，可替换为动态变量
        "client" => array(
            "cpf" => $clientCPF,
            "name" => $clientName,
            "email" => $clientEmail,
            "birthdate" => "1982-01-14", // 示例值，可替换为动态变量
            "cep" => $clientCep,
            "phone" => $clientPhone
        ),
        "items" => array(
            array(
                "reference" => "my-item-ref-0001", // 示例值
                "description" => "Product Description", // 示例值
                "quantity" => 1,
                "amount" => $amount // 使用传入的金额变量
            ),
            // 如果有多个商品，可以在这里添加更多数组元素
        ),
        "coupon" => array(
            "code" => "10DESCONTO", // 示例值
            "value" => 1000,
            "issuer" => "merchant_api"
        ),
        "shipping" => array(
            "amount" => 1000 // 示例值
        ),
        "redirect" => array(
            "success" => "https://example.com/sp_callback?success", // 示例值，可替换为 $urlCallBack
            "failed" => "https://example.com/sp_callback?failed"   // 示例值，可替换为 $urlError
        )
    );

    // ... 后续 cURL 设置
}

步骤二：使用json_encode()转换并发送

将构建好的PHP数组通过json_encode()函数转换为JSON字符串，然后将其作为CURLOPT_POSTFIELDS的值。同时，务必设置Content-Type: application/json请求头，告知API服务器请求体是JSON格式。

// ... 初始化 cURL

curl_setopt($ch, CURLOPT_URL, 'https://sandbox.splipay.com/api/orders'); // 替换为实际API URL
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

// 将PHP数组编码为JSON字符串
$jsonPayload = json_encode($postData);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonPayload);

// 设置请求头
$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer '.$_POST['token']; // 假设token从POST请求获取
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// ... 执行 cURL 请求

完整的PHP cURL示例

结合上述步骤，一个完整的PHP cURL函数示例如下：

<?php

function generatePayment($sendId, $clientCPF, $clientName, $clientEmail, $clientCep, $clientPhone, $amount, $authToken) {
    // 配置回调URL和错误URL
    $urlCallBack = "http://192.168.0.79/sistema/admin/shipList.php?transactionStatus=success";
    $urlError = "http://192.168.0.79/sistema/admin/shipList.php?transactionStatus=failed";
    $debug = true; // 调试模式开关

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://sandbox.splipay.com/api/orders'); // 替换为实际的API端点
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); // 返回响应内容而不直接输出
    curl_setopt($ch, CURLOPT_POST, 1); // 设置为POST请求

    // 构建POST数据为PHP数组
    $postData = array(
        "reference" => "my-order-ref-" . $sendId, // 使用传入的sendId作为订单参考
        "client" => array(
            "cpf" => $clientCPF,
            "name" => $clientName,
            "email" => $clientEmail,
            "birthdate" => "1982-01-14", // 假设生日是固定值或从其他地方获取
            "cep" => $clientCep,
            "phone" => $clientPhone
        ),
        "items" => array(
            array(
                "reference" => "item-ref-001",
                "description" => "Payment for Order " . $sendId,
                "quantity" => 1,
                "amount" => $amount // 金额通常以分（或最小单位）计算
            ),
        ),
        "coupon" => array( // 优惠券信息，如果不需要可移除
            "code" => "DISCOUNT10",
            "value" => 1000, // 10.00单位
            "issuer" => "merchant_api"
        ),
        "shipping" => array( // 运费信息，如果不需要可移除
            "amount" => 500 // 5.00单位
        ),
        "redirect" => array(
            "success" => $urlCallBack,
            "failed" => $urlError
        )
    );

    // 将PHP数组编码为JSON字符串
    $jsonPayload = json_encode($postData);

    // 设置POST请求体
    curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonPayload);

    // 设置HTTP请求头
    $headers = array();
    $headers[] = 'Content-Type: application/json';
    $headers[] = 'Authorization: Bearer ' . $authToken; // 使用传入的authToken
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    // 执行cURL请求
    $result = curl_exec($ch);

    // 错误处理
    if (curl_errno($ch)) {
        echo 'cURL Error: ' . curl_error($ch);
        return false;
    } else {
        // 解码API响应
        $decode = json_decode($result, true);

        if ($debug) {
            echo "<BR><BR><BR> DATA PASSED TO FUNCTION <BR>";
            echo "<br>sendId ===> " . $sendId;
            echo "<br>clientCPF ===> " . $clientCPF;
            echo "<br>clientName ===> " . $clientName;
            echo "<br>clientEmail ===> " . $clientEmail;
            echo "<br>clientCep ===> " . $clientCep;
            echo "<br>clientPhone ===> " . $clientPhone;
            echo "<br>amount ===> " . $amount;
            echo "<br>Auth Token ===> " . $authToken;
            echo "<BR><BR> JSON PAYLOAD SENT <BR>";
            echo "<pre>" . htmlspecialchars($jsonPayload) . "</pre>"; // 显示发送的JSON

            echo "<BR><BR> DATA RECEIVED FROM API <BR>";
            var_dump($decode); // 完整输出API响应

            if (isset($decode['data']['order_id'])) {
                echo '<br> payId generated by API ==> ' . $decode['data']['order_id'];
            }
            if (isset($decode['data']['url_checkout'])) {
                echo '<br> PayURL generated by API ==> ' . $decode['data']['url_checkout'];
            }
        } else {
            // 非调试模式下，处理API响应并存储到SESSION
            if (isset($decode['data']['order_id']) && isset($decode['data']['url_checkout'])) {
                $_SESSION['transactionUrl'] = $decode['data']['url_checkout'];
                $_SESSION['transactionId'] = $decode['data']['order_id'];
                $_SESSION['sendId'] = $sendId;
                return true;
            } else {
                echo "API returned an unexpected response: " . $result;
                return false;
            }
        }
    }

    curl_close($ch);
}

// 示例调用 (在实际应用中，这些值通常来自表单提交或数据库)
// session_start(); // 如果使用SESSION，需要先启动
// $token = $_POST['token'] ?? 'YOUR_STATIC_OR_DYNAMIC_AUTH_TOKEN'; // 假设token通过POST获取或是一个预设值
// generatePayment("0001", "43164853858", "John Doe", "john.doe@example.com", "18053190", "15987452584", 149900, $token);

?>

调试技巧与注意事项

检查json_encode()的返回值： 在json_encode($postData)之后，使用var_dump($jsonPayload);和json_last_error();、json_last_error_msg();来检查生成的JSON字符串是否有效，以及是否存在编码错误。
查看cURL错误信息： 始终使用curl_errno($ch)和curl_error($ch)来捕获cURL执行过程中可能发生的网络或配置错误。
检查HTTP状态码和响应头： 使用curl_getinfo($ch, CURLINFO_HTTP_CODE)获取HTTP状态码（例如200、400、500），并使用curl_getinfo($ch)获取更详细的请求信息，包括响应头。这有助于判断是客户端请求问题还是服务器端处理问题。
var_dump() API响应： 在$result = curl_exec($ch);之后，使用var_dump($result);和var_dump(json_decode($result, true));来查看API返回的原始字符串和解析后的数组，以便分析API的实际响应内容和结构。
对照API文档： 仔细核对您的PHP数组结构是否与API文档中要求的JSON请求体完全一致，包括字段名、数据类型和嵌套层级。一个小小的拼写错误或类型不匹配都可能导致API拒绝请求。
金额单位： 许多支付API要求金额以最小货币单位（如分）表示，例如149900代表1499.00。请根据API文档确认。
$_POST['token']的安全性： 在生产环境中，直接从$_POST获取敏感信息（如认证令牌）是不安全的。认证令牌通常应通过更安全的方式管理和传递，例如从环境变量、配置文件或安全存储中获取。

总结

通过采用PHP数组构建数据结构并利用json_encode()函数生成JSON请求体，可以显著提高PHP cURL发送复杂JSON数据的准确性和健壮性。结合全面的错误处理和调试技巧，开发者能够更有效地与各种RESTful API进行交互，确保数据传输的顺畅和可靠。始终以API文档为准，并对请求和响应进行充分的验证，是开发过程中不可或缺的最佳实践。

CodeIgniter在Mac上配置PHP扩展_CodeIgniterPHP扩展设置【详解】

宝塔面板下如何修改MySQL的字符集为utf8mb4支持表情？

PHP 数据库与缓存一致性设计

PHP代码复用有哪些方式_PHP include require trait对比【解答】

宝塔面板如何配置PHP-FPM慢日志？在宝塔面板中找出执行最慢的代码段