前言

cURL 是 PHP 最強大的網路傳輸工具，支援 HTTP/HTTPS、FTP、SMTP 等多種協議，能處理 Cookie、認證、表單提交、檔案上傳、代理轉發等複雜場景。本文從基礎 GET/POST 到進階應用全面解析。

一、cURL 基礎四步驟

$ch = curl_init();                    // 1. 初始化
curl_setopt($ch, CURLOPT_URL, $url);    // 2. 設定選項
$output = curl_exec($ch);               // 3. 執行
curl_close($ch);                        // 4. 釋放資源

核心選項速查

選項	說明	常用值
CURLOPT_URL	請求網址	'https://api.example.com'
CURLOPT_RETURNTRANSFER	回傳字串而非直接輸出	true (必要)
CURLOPT_HEADER	是否包含回應標頭	false
CURLOPT_TIMEOUT	總超時秒數	30
CURLOPT_CONNECTTIMEOUT	連線超時秒數	10
CURLOPT_SSL_VERIFYPEER	驗證 SSL 憑證	true (生產環境必開)
CURLOPT_FOLLOWLOCATION	自動追蹤重導向	true
CURLOPT_MAXREDIRS	最大重導向次數	5
CURLOPT_USERAGENT	自訂 User-Agent	'MyApp/1.0'

二、GET 請求與資訊獲取

$ch = curl_init('https://httpbin.org/get?key=value');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER => false,
]);
$response = curl_exec($ch);

if ($response === false) {
    throw new Exception('cURL Error: ' . curl_error($ch));
}

// 獲取傳輸資訊
$info = curl_getinfo($ch);
echo "HTTP Code: {$info['http_code']}\n";
echo "Total Time: {$info['total_time']}s\n";
echo "DNS Time: {$info['namelookup_time']}s\n";
echo "Connect Time: {$info['connect_time']}s\n";

curl_close($ch);

三、POST 表單提交

$postData = [
    'username' => 'tom',
    'password' => 'secret',
    'action'   => 'login',
];

$ch = curl_init('https://httpbin.org/post');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $postData, // 自動編碼為 application/x-www-form-urlencoded
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
// 回應包含 $_POST 資料

四、檔案上傳 (multipart/form-data)

$filePath = '/path/to/document.pdf';
$postData = [
    'file' => new CURLFile($filePath, 'application/pdf', 'document.pdf'), // PHP 5.5+
    'description' => '月度報表',
];

$ch = curl_init('https://httpbin.org/post');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $postData,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

舊版寫法 (已棄用)：'@' . $filePath 需設定 CURLOPT_SAFE_UPLOAD => false。

五、HTTP 基礎認證

curl_setopt_array($ch, [
    CURLOPT_USERPWD => 'username:password',
    CURLOPT_HTTPAUTH => CURLAUTH_BASIC, // 或 DIGEST
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_UNRESTRICTED_AUTH => true, // 重導向時保持認證
]);

六、FTP 上傳

$fp = fopen('/local/path/file.txt', 'r');
$ch = curl_init('ftp://user:pass@ftp.example.com/remote/file.txt');
curl_setopt_array($ch, [
    CURLOPT_UPLOAD => true,
    CURLOPT_INFILE => $fp,
    CURLOPT_INFILESIZE => filesize('/local/path/file.txt'),
    CURLOPT_FTPASCII => true, // 文字檔建議開啟
]);
curl_exec($ch);
fclose($fp);
curl_close($ch);

七、代理轉發

curl_setopt_array($ch, [
    CURLOPT_PROXY => '10.10.1.10:3128',
    CURLOPT_PROXYUSERPWD => 'proxy_user:proxy_pass', // 若需認證
    CURLOPT_PROXYTYPE => CURLPROXY_HTTP, // 或 SOCKS5
]);

八、串流回調處理大檔案

避免大檔案佔用記憶體，邊下載邊處理/寫入磁碟。

 function($ch, $data) use ($fp) {
        $len = fwrite($fp, $data);
        return $len; // 必須返回寫入位元組數
    },
    CURLOPT_BUFFERSIZE => 8192,
]);
curl_exec($ch);
fclose($fp);
curl_close($ch);

九、進階：多執行緒並發請求 (curl_multi)

$urls = ['https://api1.example.com', 'https://api2.example.com', 'https://api3.example.com'];
$handles = [];
$mh = curl_multi_init();

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); // 等待活動
} while ($running > 0);

$results = [];
foreach ($handles as $url => $ch) {
    $results[$url] = curl_multi_getcontent($ch);
    curl_multi_remove_handle($mh, $ch);
    curl_close($ch);
}
curl_multi_close($mh);

十、錯誤處理最佳實務

function curlRequest(string $url, array $options = []): string {
    $ch = curl_init($url);
    $defaultOptions = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_MAXREDIRS => 5,
    ];
    curl_setopt_array($ch, array_merge($defaultOptions, $options));
    
    $response = curl_exec($ch);
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    $info = curl_getinfo($ch);
    curl_close($ch);
    
    if ($errno) {
        throw new RuntimeException("cURL Error [$errno]: $error", $errno);
    }
    if ($info['http_code'] >= 400) {
        throw new HttpException("HTTP {$info['http_code']}", $info['http_code'], $response);
    }
    return $response;
}

總結

cURL 是 PHP 後端整合第三方 API、微服務通訊、檔案傳輸的核心工具。掌握選項配置、錯誤處理、串流處理與並發請求，能構建高效、穩健的網路通訊層。生產環境務必啟用 SSL 驗證、設定超時、記錄完整請求/回應日誌以利除錯。