PHP cURL 核心函數詳解：curl_init()、curl_setopt() 實戰指南

cURL 簡介

cURL (Client URL Library) 是 PHP 最強大的 HTTP 客端庫，支援 HTTP/HTTPS、FTP、FTPS、SFTP、LDAP、MQTT 等協議，提供精細的請求控制（Header、Cookie、代理、SSL、超時、斷點續傳、多線程並發），是 API 對接、爬蟲、微服務通信的標準選擇。

核心流程

1. curl_init() 初始化會話，返回句柄 $ch
2. curl_setopt() / curl_setopt_array() 設置選項
3. curl_exec() 執行請求
4. curl_close() 釋放資源

關鍵函數語法

resource curl_init ( [ string $url = null ] )
bool curl_setopt ( resource $ch, int $option, mixed $value )
bool curl_setopt_array ( resource $ch, array $options )
mixed curl_exec ( resource $ch )
void curl_close ( resource $ch )

常用選項分類速查

實戰範例集

範例 1：基礎 GET 請求

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com/users');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$response = curl_exec($ch);
if ($response === false) {
    echo "錯誤: " . curl_error($ch);
} else {
    $data = json_decode($response, true);
    print_r($data);
}
curl_close($ch);
?>

範例 2：POST JSON 數據（API 典型調用）

<?php
$ch = curl_init('https://api.example.com/orders');
$payload = json_encode(['user_id' => 123, 'items' => [['sku' => 'A001', 'qty' => 2]]]);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $access_token,
        'Accept: application/json'
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_SSL_VERIFYPEER => true, // 生產環境必須開啟
]);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
?>

範例 3：文件上傳

<?php
$ch = curl_init('https://api.example.com/upload');
$cfile = new CURLFile('/path/to/image.jpg', 'image/jpeg', 'photo.jpg'); // PHP 5.5+
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => ['file' => $cfile, 'user_id' => 123],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
?>

範例 4：流式下載大文件（不佔用記憶體）

<?php
$ch = curl_init('https://cdn.example.com/large.iso');
$fp = fopen('/tmp/large.iso', 'wb');
curl_setopt_array($ch, [
    CURLOPT_FILE => $fp, // 直接寫入文件句柄
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_TIMEOUT => 0, // 無總超時
    CURLOPT_CONNECTTIMEOUT => 30,
    CURLOPT_NOPROGRESS => false,
    CURLOPT_PROGRESSFUNCTION => function($ch, $dltotal, $dlnow, $ultotal, $ulnow) {
        if ($dltotal > 0) printf("\r下載進度: %.2f%%", $dlnow/$dltotal*100);
    }
]);
curl_exec($ch);
fclose($fp);
curl_close($ch);
?>

範例 5：並發多請求

<?php
$urls = ['https://api1.example.com', 'https://api2.example.com', 'https://api3.example.com'];
$mh = curl_multi_init();
$handles = [];
foreach ($urls as $url) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_multi_add_handle($mh, $ch);
    $handles[$url] = $ch;
}

$running = null;
do {
    curl_multi_exec($mh, $running);
    curl_multi_select($mh, 0.1); // 等待活動
} while ($running > 0);

foreach ($handles as $url => $ch) {
    $response = curl_multi_getcontent($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    echo "$url: HTTP $http_code\n";
    curl_multi_remove_handle($mh, $ch);
    curl_close($ch);
}
curl_multi_close($mh);
?>

進階技巧與避坑

• 復用句柄：同域名多請求復用 $ch，保持 Keep-Alive 連接，減少握手開銷。
• DNS 緩存：CURLOPT_DNS_CACHE_TIMEOUT（默認 120s）避免頻繁解析。
• 憑證綁定：CURLOPT_PINNEDPUBLICKEY 防中間人攻擊。
• 錯誤處理：curl_errno()、curl_error()、curl_getinfo($ch, CURLINFO_HTTP_CODE) 三重檢查。
• 內存洩漏：長運行腳本定期 curl_close() 重建句柄，釋放 libcurl 內部緩存。