file_get_contents()、file()、readfile() 雖簡單,但缺乏靈活性:
false,無細節)cURL 支援 20+ 協定(HTTP/HTTPS/FTP/SMTP/IMAP...),提供精細控制,是 PHP 進行網路通訊的標準利器。
<?php
// 1. 初始化
$ch = curl_init();
// 2. 設定選項
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.example.com/users',
CURLOPT_RETURNTRANSFER => true, // 回傳字串而非直接輸出
CURLOPT_HEADER => false, // 不包含回應標頭於 body
CURLOPT_TIMEOUT => 10, // 總超時秒數
CURLOPT_CONNECTTIMEOUT => 5, // 連線超時
CURLOPT_FOLLOWLOCATION => true, // 自動追蹤 3xx 重導向
CURLOPT_MAXREDIRS => 5, // 最大重導向次數
CURLOPT_USERAGENT => 'MyApp/1.0 (+https://example.com)',
CURLOPT_SSL_VERIFYPEER => true, // 生產環境必須驗證 SSL
CURLOPT_SSL_VERIFYHOST => 2,
]);
// 3. 執行並取得回應
$response = curl_exec($ch);
// 4. 錯誤處理與資訊取得
if ($response === false) {
$errno = curl_errno($ch);
$error = curl_error($ch);
throw new \RuntimeException("cURL error ($errno): $error");
}
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$info = curl_getinfo($ch); // 完整傳輸資訊陣列
// 5. 關閉釋放資源
curl_close($ch);
=== false<?php
$response = curl_exec($ch);
if ($response === false) { // 嚴格比較!空字串 "" 也是合法回應
throw new \Exception(curl_error($ch), curl_errno($ch));
}
curl_exec() 失敗回傳 false,成功回傳字串(可能為 "")。用 == 會誤判空字串為錯誤。
<?php
curl_exec($ch);
$info = curl_getinfo($ch);
echo "HTTP 狀態碼: {$info['http_code']}\n";
echo "總耗時: {$info['total_time']} 秒\n";
echo "DNS 解析: {$info['namelookup_time']} 秒\n";
echo "連線建立: {$info['connect_time']} 秒\n";
echo "SSL 交握: {$info['appconnect_time']} 秒\n";
echo "首位元組時間 (TTFB): {$info['starttransfer_time']} 秒\n";
echo "下載大小: {$info['size_download']} bytes\n";
echo "上傳大小: {$info['size_upload']} bytes\n";
echo "Content-Type: {$info['content_type']}\n";
<?php
$postData = [
'blog_name' => 'My Blog',
'blog_url' => 'https://example.com',
'action' => 'submit',
];
$ch = curl_init('https://example.com/api/submit');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postData, // 自動 application/x-www-form-urlencoded
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: secret123',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
// 處理回應...
curl_close($ch);
<?php
$filePath = '/path/to/photo.jpg';
$fileName = basename($filePath);
$mimeType = mime_content_type($filePath);
$postData = [
'file' => new CURLFile($filePath, $mimeType, $fileName), // PHP 5.5+ 推薦
// 舊版寫法(已棄用):'file' => "@$filePath;filename=$fileName;type=$mimeType"
'description' => 'Profile photo',
'user_id' => 123,
];
$ch = curl_init('https://api.example.com/upload');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postData,
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
注意: CURLFile 類別自 PHP 5.5 起取代 @ 前綴語法,更安全、支援明確 MIME 類型。
<?php
$url = 'https://example.com/large-file.zip';
$savePath = '/var/www/downloads/large-file.zip';
$ch = curl_init($url);
$fp = fopen($savePath, 'wb');
curl_setopt_array($ch, [
CURLOPT_FILE => $fp, // 直接寫入檔案指標,避免記憶體爆炸
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_TIMEOUT => 300, // 大檔案需較長超時
CURLOPT_PROGRESSFUNCTION => function($ch, $dlTotal, $dlNow, $ulTotal, $ulNow) {
if ($dlTotal > 0) {
printf("\r下載進度: %.2f%% (%d/%d bytes)", $dlNow/$dlTotal*100, $dlNow, $dlTotal);
}
return 0; // 繼續
},
CURLOPT_NOPROGRESS => false,
]);
curl_exec($ch);
curl_close($ch);
fclose($fp);
echo "\n下載完成\n";
<?php
$cookieJar = '/tmp/cookies.txt';
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_COOKIEJAR => $cookieJar, // 儲存回應的 Set-Cookie
CURLOPT_COOKIEFILE => $cookieJar, // 發送請求時帶入 Cookie
// ...
]);
// 登入請求
curl_setopt($ch, CURLOPT_URL, 'https://example.com/login');
curl_setopt($ch, CURLOPT_POSTFIELDS, ['user'=>'admin', 'pass'=>'secret']);
curl_exec($ch);
// 後續請求自動帶入 Cookie
curl_setopt($ch, CURLOPT_URL, 'https://example.com/dashboard');
$html = curl_exec($ch);
<?php
// Basic Auth
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
// Bearer Token
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $accessToken,
]);
<?php
$urls = [
'https://api.example.com/users/1',
'https://api.example.com/users/2',
'https://api.example.com/users/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 > 0);
$results = [];
foreach ($handles as $url => $ch) {
$results[$url] = [
'code' => curl_getinfo($ch, CURLINFO_HTTP_CODE),
'body' => curl_multi_getcontent($ch),
'error' => curl_error($ch),
];
curl_multi_remove_handle($mh, $ch);
curl_close($ch);
}
curl_multi_close($mh);
| 選項 | 說明 | 常用值 |
|---|---|---|
| CURLOPT_URL | 請求網址 | 字串 |
| CURLOPT_RETURNTRANSFER | 回傳字串而非輸出 | true |
| CURLOPT_HEADER | 包含回應標頭於輸出 | false |
| CURLOPT_FOLLOWLOCATION | 自動追蹤重導向 | true |
| CURLOPT_MAXREDIRS | 最大重導向次數 | 5-10 |
| CURLOPT_TIMEOUT | 總超時秒數 | 10-30 |
| CURLOPT_CONNECTTIMEOUT | 連線超時秒數 | 5-10 |
| CURLOPT_SSL_VERIFYPEER | 驗證 SSL 憑證 | true (生產必開) |
| CURLOPT_SSL_VERIFYHOST | 驗證 SSL 主機名 | 2 |
| CURLOPT_USERAGENT | User-Agent 標頭 | 自定義字串 |
| CURLOPT_HTTPHEADER | 自定義請求標頭陣列 | ['Header: value'] |
| CURLOPT_POST | 發送 POST | true |
| CURLOPT_POSTFIELDS | POST 資料 | 陣列或字串 |
| CURLOPT_CUSTOMREQUEST | 自定義 HTTP 方法 | 'PUT', 'DELETE', 'PATCH' |
| CURLOPT_PROXY | Proxy 伺服器 | 'https://proxy:8080' |
| CURLOPT_INTERFACE | 指定輸出網卡 IP | 'eth0' 或 IP |
| 代碼 | 常數 | 原因與對策 |
|---|---|---|
| 6 | CURLE_COULDNT_RESOLVE_HOST | DNS 解析失敗,檢查網域、DNS 設定、/etc/hosts |
| 7 | CURLE_COULDNT_CONNECT | 無法連線,檢查 IP、Port、防火牆、SSL 憑證 |
| 28 | CURLE_OPERATION_TIMEDOUT | 逾時,調大 TIMEOUT 或檢查網路延遲 |
| 35 | CURLE_SSL_CONNECT_ERROR | SSL 交握失敗,憑證過期、不信任、協定版本不符 |
| 51 | CURLE_SSL_PEER_CERTIFICATE | 對端憑證驗證失敗,需更新 CA Bundle 或正確設定 VERIFYPEER |
| 60 | CURLE_SSL_CACERT | CA 憑證問題,設定 CURLOPT_CAINFO 指向 cacert.pem |
cURL 是 PHP 網路通訊的瑞士刀。掌握四步驟流程、嚴格錯誤判斷、資訊擷取、POST/檔案上傳、串流下載、Cookie/驗證、並行請求,即能應對 95% 的 HTTP 整合場景。生產環境務必啟用 SSL 驗證、設定合理超時、記錄完整錯誤日誌,並考慮引入 Guzzle、Symfony HttpClient 等高層封裝以提升開發體驗與可維護性。