PHP 透過 curl_init() → curl_setopt() 設定選項 → curl_exec() 執行 → curl_close() 關閉,是呼叫 HTTP API 最常用方式。
<?php
$url = 'https://api.example.com/v1/order';
$data = ['order_id' => '202401001', 'amount' => 199.00];
$header = [
'Content-Type: application/json',
'Authorization: Bearer YOUR_TOKEN',
'Accept: application/json'
];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => $header,
CURLOPT_RETURNTRANSFER => true, // 回傳字串而非直接輸出
CURLOPT_TIMEOUT => 10, // 連線逾時秒數
CURLOPT_CONNECTTIMEOUT => 5, // 建立連線逾時
CURLOPT_SSL_VERIFYPEER => true, // 驗證 SSL 憑證 (生產必開)
CURLOPT_SSL_VERIFYHOST => 2,
// CURLOPT_CAINFO => '/path/to/cacert.pem', // 若驗證失敗指定 CA 憑證
]);
$response = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($errno) {
error_log("cURL Error [$errno]: $error");
// 處理失敗...
}
$result = json_decode($response, true);
if ($httpCode >= 200 && $httpCode < 300) {
// 成功處理 $result
} else {
// 依 $httpCode 處理錯誤
}
?>
| 類別 | 選項 | 說明 |
|---|---|---|
| 行為控制 | CURLOPT_RETURNTRANSFER | true 回傳字串,false 直接輸出 |
| CURLOPT_FOLLOWLOCATION | true 跟隨 3xx 重導向 | |
| CURLOPT_MAXREDIRS | 最大重導向次數 (預設 20) | |
| CURLOPT_AUTOREFERER | 重導向時自動帶 Referer | |
| CURLOPT_FAILONERROR | true 時 HTTP ≥400 視為失敗 | |
| CURLOPT_TIMEOUT | 總執行逾時秒數 | |
| CURLOPT_CONNECTTIMEOUT | 建立連線逾時秒數 | |
| CURLOPT_NOSIGNAL | 多線程環境必開 (避免信號衝突) | |
| 請求設定 | CURLOPT_POST | true 發送 POST |
| CURLOPT_POSTFIELDS | POST 資料 (陣列→multipart, 字串→application/x-www-form-urlencoded) | |
| CURLOPT_HTTPHEADER | 自定標頭陣列 | |
| CURLOPT_USERAGENT | User-Agent 字串 | |
| CURLOPT_COOKIE | 攜帶 Cookie 字串 | |
| CURLOPT_COOKIEJAR/FILE | 儲存/讀取 Cookie 檔案 | |
| SSL/安全 | CURLOPT_SSL_VERIFYPEER | 驗證對端憑證 (生產必 true) |
| CURLOPT_SSL_VERIFYHOST | 2=驗證 CN/SubjectAltName 匹配主機名 | |
| CURLOPT_CAINFO | CA 憑證束路徑 | |
| CURLOPT_SSLCERT/KEY | 客戶端憑證 (雙向 TLS) | |
| CURLOPT_PROXY | 代理伺服器 ip:port |
<?php
// GET with query string
$ch = curl_init("$url?" . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// 檔案上傳 (PHP 5.5+ 使用 CURLFile)
$post = ['file' => new CURLFile('/path/to/file.png', 'image/png', 'filename.png')];
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
// 並發請求 (curl_multi)
$mh = curl_multi_init();
$handles = [];
foreach ($urls as $u) {
$ch = curl_init($u);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $ch);
$handles[] = $ch;
}
$running = null;
do { curl_multi_exec($mh, $running); } while ($running);
foreach ($handles as $ch) {
$result = curl_multi_getcontent($ch);
curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);
?>
curl_errno() 與 curl_getinfo($ch, CURLINFO_HTTP_CODE)。CURLOPT_TIMEOUT 避免阻塞。