PHP cURL 模擬 POST 請求完整範例與進階技巧

基本 POST 請求

<?php
$url = 'https://api.example.com/endpoint';
$data = [
    'name' => 'tanteng',
    'email' => 'user@example.com',
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $data,           // 陣列自動編碼為 application/x-www-form-urlencoded
    CURLOPT_RETURNTRANSFER => true,            // 回傳字串而非直接輸出
    CURLOPT_HEADER         => false,           // 不包含回應標頭
    CURLOPT_TIMEOUT        => 10,              // 秒，連線逾時
    CURLOPT_CONNECTTIMEOUT => 5,               // 秒，建立連線逾時
    CURLOPT_SSL_VERIFYPEER => true,            // 生產環境必須驗證 SSL
    CURLOPT_FOLLOWLOCATION => true,            // 支援重導向
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception('cURL 錯誤: ' . curl_error($ch), curl_errno($ch));
}

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP $httpCode\n";
echo $response;

遠端接收端範例

<?php
// test.php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $name = $_POST['name'] ?? '';
    if ($name !== '') {
        echo "您好，{$name}！";
    } else {
        http_response_code(400);
        echo '缺少 name 參數';
    }
}

進階場景

發送 JSON 資料

<?php
$jsonData = json_encode(['user_id' => 123, 'action' => 'login']);
curl_setopt_array($ch, [
    CURLOPT_POSTFIELDS => $jsonData,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($jsonData),
    ],
]);

檔案上傳 (multipart/form-data)

<?php
// PHP 5.5+ 使用 CURLFile
$data = [
    'file' => new CURLFile('/path/to/image.jpg', 'image/jpeg', 'avatar.jpg'),
    'user_id' => 456,
];
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

攜帶 Cookie 與 Session

<?php
$cookieFile = sys_get_temp_dir() . '/cookie.txt';
curl_setopt_array($ch, [
    CURLOPT_COOKIEJAR  => $cookieFile, // 儲存回應 Cookie
    CURLOPT_COOKIEFILE => $cookieFile, // 發送儲存的 Cookie
]);

自訂 User-Agent 與 Referer

<?php
curl_setopt_array($ch, [
    CURLOPT_USERAGENT => 'MyApp/1.0 (+https://example.com)',
    CURLOPT_REFERER   => 'https://example.com/referer-page',
]);

錯誤處理與除錯

<?php
// 開啟詳細資訊
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verboseLog = fopen('php://temp', 'rw+');
curl_setopt($ch, CURLOPT_STDERR, $verboseLog);

// 執行後
rewind($verboseLog);
echo stream_get_contents($verboseLog);

常見 HTTP 狀態碼處理