萬盛學電腦網

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

PHP cURL 入門到精通:基礎操作、常用選項與實戰範例

cURL 是 PHP 中功能最強大的 HTTP 客戶端庫,支援 HTTP/HTTPS、FTP、FTPS、SFTP、SCP、TELNET、LDAP、FILE 等多種協議,並完美處理 Cookie、Session、認證、代理、文件上傳、斷點續傳等複雜場景。相比之下,file_get_contents() 僅適合簡單 GET 請求,面對表單提交、Cookie 維持、HTTPS 驗證等場景無能為力。

一、環境準備:啟用 cURL 擴展

  1. 打開 php.ini
  2. 搜尋 extension=php_curl.dll(Windows)或 extension=curl.so(Linux/Mac)
  3. 去掉前面的分號 ;
  4. 重啟 Web 伺服器(Apache/Nginx + PHP-FPM)
  5. 驗證:php -m | grep curl 或 phpinfo() 中出現 cURL support enabled

二、cURL 四步基本流程

  1. 初始化:$ch = curl_init(); 返回 cURL 句柄
  2. 設置選項:curl_setopt($ch, OPTION, VALUE); 可多次調用
  3. 執行請求:$output = curl_exec($ch); 返回響應體(或直接輸出)
  4. 關閉句柄:curl_close($ch); 釋放資源

三、最小化 GET 請求範例

<?php
$ch = curl_init();

// 目標 URL
curl_setopt($ch, CURLOPT_URL, "https://www.baidu.com");

// 關鍵:返回響應體而非直接輸出(預設 CURLOPT_RETURNTRANSFER=0 直接輸出)
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// 不需要響應標頭
curl_setopt($ch, CURLOPT_HEADER, 0);

// 執行
$html = curl_exec($ch);

// 錯誤處理
if ($html === false) {
    echo 'cURL Error: ' . curl_error($ch);
} else {
    echo $html;
}

curl_close($ch);
?>

四、高頻選項速查表(CURLOPT_* 常用集)

選項常量用途典型值
CURLOPT_URL請求地址"https://api.example.com/users"
CURLOPT_RETURNTRANSFER1=返回字串, 0=直接輸出1
CURLOPT_HEADER1=包含響應標頭, 0=不包含0
CURLOPT_POST1=啟用 POST1
CURLOPT_POSTFIELDSPOST 數據(陣列=multipart/form-data, 字串=application/x-www-form-urlencoded)['field'=>'value']
CURLOPT_HTTPHEADER自定義請求標頭陣列['Authorization: Bearer xxx', 'Content-Type: application/json']
CURLOPT_TIMEOUT最大執行秒數(總超時)30
CURLOPT_CONNECTTIMEOUT連接階段超時秒數10
CURLOPT_SSL_VERIFYPEER驗證 SSL 憑證(生產環境建議 1)1 (開發可設 0)
CURLOPT_SSL_VERIFYHOST檢查 SSL 憑證 CN 與主機名匹配2
CURLOPT_FOLLOWLOCATION1=自動跟隨 3xx 重定向1
CURLOPT_MAXREDIRS最大重定向次數5
CURLOPT_COOKIEJARCookie 儲存文件路徑(持久化)/tmp/cookies.txt
CURLOPT_COOKIEFILE讀取 Cookie 文件/tmp/cookies.txt
CURLOPT_USERAGENT自定義 User-Agent'Mozilla/5.0 (compatible; MyBot/1.0)'
CURLOPT_PROXY代理伺服器'127.0.0.1:8080'
CURLOPT_PROXYUSERPWD代理認證 "user:pwd"'user:pass'

五、實戰範例:POST JSON + 自定義 Header + 超時控制

<?php
function postJson($url, $data, $timeout = 10) {
    $ch = curl_init($url);
    
    $options = [
        CURLOPT_POST           => 1,
        CURLOPT_POSTFIELDS     => json_encode($data),
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Accept: application/json',
            'User-Agent: MyApp/1.0'
        ],
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_TIMEOUT        => $timeout,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_SSL_VERIFYPEER => 1, // 生產環境必開
    ];
    
    curl_setopt_array($ch, $options);
    
    $response = curl_exec($ch);
    $errno    = curl_errno($ch);
    $error    = curl_error($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    curl_close($ch);
    
    if ($errno) {
        return ['success' => false, 'error' => $error, 'errno' => $errno];
    }
    
    return [
        'success'   => true,
        'http_code' => $httpCode,
        'body'      => json_decode($response, true),
        'raw'       => $response
    ];
}

// 使用
$result = postJson('https://httpbin.org/post', ['name' => 'Alice', 'age' => 25]);
var_dump($result);
?>

六、文件上傳(multipart/form-data)

<?php
$ch = curl_init('https://api.example.com/upload');
$filePath = '/path/to/local/file.jpg';

// PHP 5.5+ 推薦使用 CURLFile 類(安全、支援檔名/MIME)
$cfile = new CURLFile($filePath, 'image/jpeg', 'avatar.jpg');

$data = [
    'file'     => $cfile,
    'user_id'  => 123,
    'token'    => 'abcxyz'
];

curl_setopt_array($ch, [
    CURLOPT_POST           => 1,
    CURLOPT_POSTFIELDS     => $data,
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_TIMEOUT        => 30,
]);

$resp = curl_exec($ch);
curl_close($ch);
?>

舊版寫法(已棄用,不安全): '@'.$filePath.';filename=xxx.jpg;type=image/jpeg' 需開啟 CURLOPT_SAFE_UPLOAD = false,強烈不建議。

七、錯誤排查清單

  • curl_error($ch):獲取最後一次錯誤描述
  • curl_errno($ch):錯誤代碼(如 28=超時, 60=SSL 憑證驗證失敗, 7=連接失敗)
  • curl_getinfo($ch):獲取詳細傳輸資訊(耗時、HTTP 碼、解析 IP 等)
  • 開發環境可暫時關閉 SSL 驗證:CURLOPT_SSL_VERIFYPEER => 0, CURLOPT_SSL_VERIFYHOST => 0

總結

cURL 是 PHP 後端開發「瑞士軍刀」。熟記 四步流程、掌握 高頻選項、善用 curl_setopt_array() 批量設置、務必做 錯誤處理與超時控制,即可應對 99% 的 HTTP 交互場景。下一步可探索 curl_multi 並發請求、斷點續傳、WebSocket 等進階用法。

copyright © 萬盛學電腦網 all rights reserved