PHP cURL 完整入門教程：從基礎請求到進階應用

為何選擇 cURL？

相比 file_get_contents()、file()、readfile() 等原生函數，cURL 提供：

• 完整的 HTTP 協議支援（Header、Cookie、認證、代理）
• 靈活的選項配置（超時、重定向、SSL 驗證、傳輸限制）
• 詳細的傳輸資訊獲取（耗時、速度、HTTP 狀態碼等）
• 支援 POST、PUT、文件上傳、FTP 等多種操作

核心四步驟

<?php
// 1. 初始化
$ch = curl_init();

// 2. 設置選項（核心）
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com/data');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 返回字串而非直接輸出
curl_setopt($ch, CURLOPT_TIMEOUT, 10);          // 連接超時秒數
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 開發環境可關閉 SSL 驗證

// 3. 執行請求
$response = curl_exec($ch);

// 4. 錯誤處理與資源釋放
if ($response === false) {
    throw new Exception('cURL Error: ' . curl_error($ch));
}
curl_close($ch);

// 處理回應
$data = json_decode($response, true);

常見應用場景

1. GET 請求攜帶參數

$params = ['page' => 1, 'limit' => 20];
$url = 'https://api.example.com/items?' . http_build_query($params);
curl_setopt($ch, CURLOPT_URL, $url);

2. POST 表單提交

$postData = ['username' => 'admin', 'password' => 'secret'];
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); // 自動設為 application/x-www-form-urlencoded

3. JSON API 請求

$jsonData = json_encode(['action' => 'create', 'data' => [...]]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData)
]);

4. 文件上傳

$filePath = '/path/to/file.zip';
$postData = [
    'file' => new CURLFile($filePath, 'application/zip', 'backup.zip'), // PHP 5.5+ 推薦
    // 舊版：'file' => '@' . $filePath
    'folder' => 'backups'
];
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

5. HTTP Basic 認證

curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

6. 使用代理

curl_setopt($ch, CURLOPT_PROXY, '127.0.0.1:8080');
curl_setopt($ch, CURLOPT_PROXYUSERPWD, 'proxy_user:proxy_pass'); // 若代理需認證

7. 獲取詳細傳輸資訊

$response = 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 "下載速度: {$info['speed_download']} bytes/s\n";

進階：回調函數處理流式數據

curl_setopt($ch, CURLOPT_WRITEFUNCTION, function($ch, $chunk) {
    // 即時處理每個數據塊（如寫入文件、推送到 WebSocket）
    fwrite($fp, $chunk);
    return strlen($chunk); // 必須返回已處理長度
});

FTP 上傳範例

$fp = fopen('/local/file.txt', 'r');
curl_setopt($ch, CURLOPT_URL, 'ftp://user:pass@ftp.example.com/remote/file.txt');
curl_setopt($ch, CURLOPT_UPLOAD, true);
curl_setopt($ch, CURLOPT_INFILE, $fp);
curl_setopt($ch, CURLOPT_INFILESIZE, filesize('/local/file.txt'));
curl_setopt($ch, CURLOPT_FTPASCII, true); // 文本文件啟用 ASCII 模式
curl_exec($ch);
fclose($fp);

錯誤處理最佳實踐

if (curl_errno($ch)) {
    $errorNo = curl_errno($ch);
    $errorMsg = curl_error($ch);
    // 記錄日誌、拋出異常、重試邏輯
    error_log("cURL [$errorNo]: $errorMsg");
}