PHP cURL 發送 JSON 資料完整範例（POST、Header 設定、錯誤處理）

呼叫 RESTful API 時常需以 JSON 格式 POST 資料。關鍵在於設定正確的 Content-Type: application/json 標頭，並將 PHP 陣列 json_encode 後送出。本文提供三種封裝層級的範例：直接呼叫、可重用函式、實際業務 JSON 結構（微信選單建立）。

核心關鍵點

$data = ['name' => 'Hagrid', 'age' => 36];
$json = json_encode($data);

$ch = curl_init('https://api.example.com/users');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS    => $json,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER    => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($json),
    ],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

必設 Header：Content-Type: application/json 告知伺服器請求體格式；Content-Length 雖非強制但建議加上，避免某些代理/伺服器拒絕 chunked 請求。

範例一：基礎 POST JSON

<?php
$data = ['name' => 'Hagrid', 'age' => '36'];
$json = json_encode($data);

$ch = curl_init('https://api.local/rest/users');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($json),
]);
$result = curl_exec($ch);
if ($result === false) {
    throw new Exception('cURL Error: ' . curl_error($ch));
}
curl_close($ch);
var_dump(json_decode($result, true));

範例二：封裝成可重用函式（支援錯誤碼、原始回應）

function httpPostJson(string $url, array $data, array $extraHeaders = []): array {
    $json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST            => true,
        CURLOPT_POSTFIELDS      => $json,
        CURLOPT_RETURNTRANSFER  => true,
        CURLOPT_HTTPHEADER      => array_merge([
            'Content-Type: application/json; charset=utf-8',
            'Content-Length: ' . strlen($json),
        ], $extraHeaders),
        CURLOPT_TIMEOUT         => 10,
        CURLOPT_CONNECTTIMEOUT  => 5,
        CURLOPT_SSL_VERIFYPEER  => true, // 生產環境保持 true
    ]);
    $response = curl_exec($ch);
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return [
        'http_code' => $httpCode,
        'body'      => $response,
        'error_no'  => $errno,
        'error_msg' => $error,
        'decoded'   => $errno === 0 ? json_decode($response, true) : null,
    ];
}

// 使用
$res = httpPostJson('https://api.example.com/orders', ['item_id' => 123, 'qty' => 2]);
if ($res['http_code'] === 200) {
    // 成功
}

範例三：複雜巢狀 JSON（微信自訂選單建立）

$menuJson = '{
    "button": [
        {"type":"click","name":"今日歌曲","key":"V1001_TODAY_MUSIC"},
        {"type":"click","name":"歌手簡介","key":"V1001_TODAY_SINGER"},
        {"name":"菜單","sub_button":[
            {"type":"click","name":"hello world","key":"V1001_HELLO_WORLD"},
            {"type":"click","name":"贊一下我們","key":"V1001_GOOD"}
        ]}
    ]
}';

$url = 'https://api.weixin.qq.com/cgi-bin/menu/create?access_token=' . $accessToken;
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS    => $menuJson,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER    => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($menuJson),
    ],
]);
$response = curl_exec($ch);
// 成功回傳：{"errcode":0,"errmsg":"ok"}
curl_close($ch);

常見坑點檢查清單

現代替代：Guzzle / Symfony HttpClient

新專案建議使用 guzzlehttp/guzzle 或 symfony/http-client，提供 PSR-18 介面、中介軟體、非同步、自動重試等企業級功能，程式碼更簡潔：

$client = new \GuzzleHttp\Client();
$response = $client->post($url, ['json' => $data]); // 自動 json_encode + Header
$data = json_decode($response->getBody(), true);

1. 上一篇文章： PHP 獲取 Checkbox 群組值的完整指南（陣列處理、資料庫存儲、批次操作）
2. 下一篇文章： PHP 陣列過濾利器：array_filter 移除空值、array_unique 去重、二維陣列去重

PHP 相關知識

PHP 手動構建 Excel 2007 文件：ZipArchive 實戰演練

從零手寫一個 .xlsx 文件：理解 OpenXML 結構的

ThinkPHP 多模組端口配置實戰：配置陣列詳解

配置檔案結構概覽 ThinkPHP 專案常見的 config

WampServer 修改默認網站目錄完整教程：httpd.conf、wampmanager.ini、wampmanager.tpl 三文件聯動

WampServer 修改默認網站目錄完整教程：httpd.

無刷新檔案上傳兩大方案：AJAX FormData 與 iframe 完整實作

無刷新檔案上傳兩大方案：AJAX FormData 與 if