PHP cURL 選項完整參考手冊：分類詳解與實務應用

cURL 是 PHP 最強大的 HTTP 客戶端庫，選項超過 200 個。本文將所有選項按資料類型分為四大類，並標註常用與進階選項。

第一類：布林值選項 (TRUE/FALSE)

第二類：整數值選項

第三類：字串值選項

第四類：陣列值選項

資源型別選項 (Stream Resource)

回呼函式選項

常用組合範例

// 標準 GET 請求
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.example.com/data',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_USERAGENT => 'MyApp/1.0',
]);
$response = curl_exec($ch);
curl_close($ch);

// POST JSON 資料
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.example.com/submit',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
curl_close($ch);

// 檔案上傳 (PHP 5.5+ 建議使用 CURLFile)
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.example.com/upload',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('/path/to/file.jpg', 'image/jpeg', 'filename.jpg'),
        'field2' => 'value',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

錯誤處理最佳實踐

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FAILONERROR, true); // 4xx/5xx 觸發錯誤

$response = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($errno) {
    // 網路層錯誤：連線失敗、逾時、DNS 解析失敗等
    throw new Exception("cURL Error [$errno]: $error");
}

$httpCode = $info['http_code'];
if ($httpCode >= 400) {
    // 應用層錯誤
    throw new Exception("HTTP Error $httpCode: $response");
}