萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP cURL 完整入門指南:從基礎 GET/POST 到檔案上傳下載、錯誤處理與進階技巧

為什麼選擇 cURL 而非 file_get_contents?

file_get_contents()、file()、readfile() 雖簡單,但缺乏靈活性:

  • 無法發送 POST 請求、自定義 Header、Cookie
  • 不支援檔案上傳、HTTP 驗證、Proxy
  • 錯誤處理薄弱(僅回傳 false,無細節)
  • 無法取得 HTTP 狀態碼、回應標頭、傳輸時間等元資料

cURL 支援 20+ 協定(HTTP/HTTPS/FTP/SMTP/IMAP...),提供精細控制,是 PHP 進行網路通訊的標準利器。

cURL 四步驟核心流程

<?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";

發送 POST 請求與表單資料

<?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);

檔案上傳(multipart/form-data)

<?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";

進階技巧與常見場景

1. Cookie 管理(登入狀態保持)

<?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);

2. HTTP 基礎驗證 / Bearer Token

<?php
// Basic Auth
curl_setopt($ch, CURLOPT_USERPWD, 'username:password');

// Bearer Token
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,
]);

3. 並行請求(curl_multi)

<?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);

4. 常見 CURLOPT 選項速查

選項說明常用值
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_USERAGENTUser-Agent 標頭自定義字串
CURLOPT_HTTPHEADER自定義請求標頭陣列['Header: value']
CURLOPT_POST發送 POSTtrue
CURLOPT_POSTFIELDSPOST 資料陣列或字串
CURLOPT_CUSTOMREQUEST自定義 HTTP 方法'PUT', 'DELETE', 'PATCH'
CURLOPT_PROXYProxy 伺服器'https://proxy:8080'
CURLOPT_INTERFACE指定輸出網卡 IP'eth0' 或 IP

常見錯誤代碼對照

代碼常數原因與對策
6CURLE_COULDNT_RESOLVE_HOSTDNS 解析失敗,檢查網域、DNS 設定、/etc/hosts
7CURLE_COULDNT_CONNECT無法連線,檢查 IP、Port、防火牆、SSL 憑證
28CURLE_OPERATION_TIMEDOUT逾時,調大 TIMEOUT 或檢查網路延遲
35CURLE_SSL_CONNECT_ERRORSSL 交握失敗,憑證過期、不信任、協定版本不符
51CURLE_SSL_PEER_CERTIFICATE對端憑證驗證失敗,需更新 CA Bundle 或正確設定 VERIFYPEER
60CURLE_SSL_CACERTCA 憑證問題,設定 CURLOPT_CAINFO 指向 cacert.pem

總結

cURL 是 PHP 網路通訊的瑞士刀。掌握四步驟流程、嚴格錯誤判斷、資訊擷取、POST/檔案上傳、串流下載、Cookie/驗證、並行請求,即能應對 95% 的 HTTP 整合場景。生產環境務必啟用 SSL 驗證、設定合理超時、記錄完整錯誤日誌,並考慮引入 Guzzle、Symfony HttpClient 等高層封裝以提升開發體驗與可維護性。

copyright © 萬盛學電腦網 all rights reserved