PHP 調用外部 HTTP 接口：從 file_get_contents 到 Guzzle 進階指南

PHP 調用外部 HTTP API 是微服務架構、第三方集成、爬蟲的基礎操作。從原生函數到專業 HTTP 客端，選擇合適工具能大幅提升開發效率與系統穩定性。

層級 1：原生基礎函數（簡單場景）

file_get_contents() - GET 請求最簡單

$url = "https://api.example.com/user?id=123&type=2";
$response = file_get_contents($url);
$data = json_decode($response, true);

• 前提： allow_url_fopen = On (php.ini)
• 缺點： 無超時控制、無錯誤詳情、無並發、無重試、無 HTTPS 驗證配置
• 適用： 內網可信服務、一次性腳本、極簡需求

stream_context_create() - 進階原生選項

$context = stream_context_create([
  'http' => [
    'method'  => 'POST',
    'header'  => "Content-Type: application/json\r\nAuthorization: Bearer $token",
    'content' => json_encode(['name' => 'John']),
    'timeout' => 10, // 秒
    'ignore_errors' => true, // 獲取 4xx/5xx 響應體
  ],
  'ssl' => [
    'verify_peer' => true,
    'verify_peer_name' => true,
  ]
]);
$response = file_get_contents('https://api.example.com/users', false, $context);

層級 2：cURL 擴展（功能完整、性能優異）

$ch = curl_init('https://api.example.com/users');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode(['name' => 'John']),
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token,
  ],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 10,
  CURLOPT_CONNECTTIMEOUT => 5,
  CURLOPT_SSL_VERIFYPEER => true,
  CURLOPT_SSL_VERIFYHOST => 2,
]);
$response = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
$info = curl_getinfo($ch); // HTTP 碼、耗時、證書信息等
curl_close($ch);

• 優勢： 完整 HTTP/HTTPS 控制、多請求並發 (curl_multi)、斷點續傳、代理、證書釘選
• 缺點： API 冗長、手動資源管理、錯誤處理分散

層級 3：Guzzle 7+（現代 PHP 首選，Composer 安裝）

composer require guzzlehttp/guzzle

基礎用法

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
  'base_uri' => 'https://api.example.com/',
  'timeout'  => 10.0,
  'verify'   => true, // SSL 驗證
]);

try {
  $response = $client->post('users', [
    'json' => ['name' => 'John'], // 自動設置 Content-Type + json_encode
    'headers' => ['Authorization' => 'Bearer ' . $token],
  ]);
  
  $statusCode = $response->getStatusCode(); // 201
  $data = json_decode($response->getBody()->getContents(), true);
  
} catch (RequestException $e) {
  if ($e->hasResponse()) {
    $errorBody = $e->getResponse()->getBody()->getContents();
  }
  // 記錄日誌、拋出業務異常...
}

進階特性

選型決策矩陣

生產環境必備配置清單

1. 超時控制： 連接超時 (3-5s) + 讀取超時 (10-30s)，防止掛死
2. 重試策略： 指數退避 + 抖動，僅重試冪等請求 (GET/HEAD/PUT/DELETE)
3. 熔斷器： 連續失敗達閾值快速失效，避免雪崩
4. 監控指標： 延遲分位數、錯誤率、吞吐量、連接池狀態
5. 敏感信息過濾： 日誌記錄時脫敏 Token、密碼、PII 數據
6. 證書管理： 生產環境強制 verify_peer=true，內網可用自簽 CA 束

從 file_get_contents 起步，到 Guzzle 成體系，工具升級本質是為了**可靠性、可觀測性、可維護性**。