PHP cURL 函數完整指南：HTTP 請求與資料傳輸
簡介
cURL (Client URL Library) 透過 libcurl 函式庫支援多種協定 (HTTP、HTTPS、FTP、FTPS、SCP、SFTP、LDAP、DICT、TELNET、FILE 等) 進行資料傳輸。功能涵蓋 GET/POST/PUT、檔案上傳、Cookie 處理、Proxy、SSL 憑證驗證、多執行緒併發請求等。PHP 4.0.2 引入，需安裝 libcurl 7.10.5+ (PHP 5.0+)。
安裝與需求
- Linux：編譯 PHP 時加入
--with-curl[=DIR]，DIR 為 libcurl 安裝路徑 (含 include/curl、lib/libcurl.a)。
- Windows：確保
libeay32.dll、ssleay32.dll 在 PATH 環境變數目錄下 (通常放在 PHP 目錄)。啟用 extension=php_curl.dll。
資源類型
- cURL 控制代碼 (
curl_init() 返回)
- cURL 多執行緒控制代碼 (
curl_multi_init() 返回)
核心函數分類速查
| 函數 | 說明 |
|---|
curl_init() | 初始化 cURL 會話 |
curl_setopt() | 設定單一傳輸選項 |
curl_setopt_array() | 批次設定選項 |
curl_exec() | 執行 cURL 會話 |
curl_close() | 關閉 cURL 會話 |
curl_getinfo() | 取得最後傳輸資訊 (HTTP 代碼、耗時、大小等) |
curl_errno() / curl_error() | 取得錯誤代碼/訊息 |
curl_strerror() | 錯誤代碼轉文字描述 |
curl_reset() | 重置所有選項 |
curl_version() | 取得 cURL 版本資訊 |
多執行緒 (併發) 函數
| 函數 | 說明 |
|---|
curl_multi_init() | 建立多執行緒控制代碼 |
curl_multi_add_handle() | 加入單一 cURL 控制代碼 |
curl_multi_exec() | 執行併發請求 |
curl_multi_select() | 等待活動連線 |
curl_multi_info_read() | 讀取完成傳輸的資訊 |
curl_multi_remove_handle() | 移除控制代碼 |
curl_multi_close() | 關閉多執行緒控制代碼 |
共享與暫停
curl_share_init() / curl_share_setopt() / curl_share_close() — 共享 Cookie/DNS/SSL sessioncurl_pause() — 暫停/恢復連線
URL 編碼/解碼
curl_escape() / curl_unescape()
檔案上傳 (PHP 5.5+)
curl_file_create() — 建立 CURLFile 物件 (取代 @ 前綴)
常用選項 (CURLOPT_*) 速查
| 選項 | 說明 |
|---|
| CURLOPT_URL | 請求網址 |
| CURLOPT_RETURNTRANSFER | true 時返回字串而非直接輸出 |
| CURLOPT_POST | true 發送 POST 請求 |
| CURLOPT_POSTFIELDS | POST 資料 (陣列或字串) |
| CURLOPT_HTTPHEADER | 自訂 HTTP 標頭陣列 |
| CURLOPT_SSL_VERIFYPEER | 驗證 SSL 憑證 (生產環境建議 true) |
| CURLOPT_SSL_VERIFYHOST | 驗證 SSL 主機名 (2 為嚴格) |
| CURLOPT_CAINFO | CA 憑證檔案路徑 |
| CURLOPT_TIMEOUT | 最大執行秒數 |
| CURLOPT_CONNECTTIMEOUT | 連線逾時秒數 |
| CURLOPT_FOLLOWLOCATION | 跟隨重導向 |
| CURLOPT_MAXREDIRS | 最大重導向次數 |
| CURLOPT_COOKIEJAR | 儲存 Cookie 的檔案 |
| CURLOPT_COOKIEFILE | 讀取 Cookie 的檔案 |
| CURLOPT_USERAGENT | User-Agent 字串 |
| CURLOPT_PROXY | Proxy 伺服器位址 |
| CURLOPT_HTTPAUTH | HTTP 驗證方式 (CURLAUTH_BASIC 等) |
| CURLOPT_USERPWD | 驗證帳號密碼 "user:pass" |
實用範例
1. 簡單 GET 請求
<?php
$ch = curl_init('https://api.example.com/users');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
$data = json_decode($response, true);
print_r($data);
}
curl_close($ch);
?>
2. POST JSON 資料
<?php
$data = ['name' => 'John', 'email' => 'john@example.com'];
$ch = curl_init('https://api.example.com/users');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Accept: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_SSL_VERIFYPEER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
?>
3. 檔案上傳
<?php
$ch = curl_init('https://api.example.com/upload');
$cfile = curl_file_create('/path/to/file.pdf', 'application/pdf', 'document.pdf');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => ['file' => $cfile],
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
?>
4. 併發多請求
<?php
$urls = [
'https://api.example.com/1',
'https://api.example.com/2',
'https://api.example.com/3',
];
$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);
} while ($running);
foreach ($handles as $url => $ch) {
$content = curl_multi_getcontent($ch);
echo "$url: " . strlen($content) . " bytes\n";
curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);
?>
錯誤處理與除錯建議
- 永遠檢查
curl_errno()，失敗時記錄 curl_error() 與 curl_getinfo()。
- 生產環境 必須 啟用
CURLOPT_SSL_VERIFYPEER 並設定 CURLOPT_CAINFO 指向有效 CA 憑證包。
- 設定合理的
CURLOPT_TIMEOUT 避免腳本卡死。
- 大量請求時使用多執行緒 (
curl_multi_*) 大幅提升效能。
