【PHP】LaravelでHTTPクライアントを使う方法

対象バージョン: Laravel 13.x / PHP 8.3+（2026年時点のシリーズ基準）
一次ソース: HTTP Client / Release Notes

Laravel 13.x で、外部サービスへ HTTP リクエストを送るときの基本を整理します。使うのはフレームワーク同梱の HTTP クライアント（Http ファサード）です。API を「作る」話ではなく、外向きに「呼び出す」話が中心です。GET / POST から、ヘッダー・タイムアウト、レスポンスの見方、エラー時の throw、テスト用の Http::fake までを短く通します。

この記事で分かること

• Http ファサードで外向きリクエストを送る方法
• JSON / フォーム / クエリ、ヘッダー、Bearer トークンの付け方
• レスポンスの判定（successful / failed など）と throw
• テストでのスタブ（Http::fake / assertSent）の最小例

---

対象バージョンと前提

本記事の前提は Laravel 13.x / PHP 8.3+ です。Laravel 13.x は PHP 8.3 以上を要求します（Release Notes）。調査時点で確認した laravel/framework 13.x の最新 stable は v13.34.0（2026-09-29）です。

ここで扱うのは 外向きの HTTP リクエスト（自アプリから他サーバーへ）です。自アプリが REST API を公開する手順とは役割が違います。コードでは次のようにファサードを import します。

use Illuminate\Support\Facades\Http;

---

HTTP クライアントとは

Laravel は、Guzzle HTTP クライアントを包んだ、表現力のある薄い API を提供します。外向きリクエストは Http ファサードの head / get / post / put / patch / delete などで送ります。Http::get などは Illuminate\Http\Client\Response を返します。

---

基本リクエスト

よく使う動詞は次のとおりです。

$response = Http::get('https://example.com/users');
$response = Http::post('https://example.com/users', ['name' => 'Taylor']);
$response = Http::put('https://example.com/users/1', ['name' => 'Taylor']);
$response = Http::patch('https://example.com/users/1', ['name' => 'Taylor']);
$response = Http::delete('https://example.com/users/1');

必要なら Http::head(...) も使えます。

---

リクエストデータ

post / put / patch の第2引数に配列を渡すと、既定では JSON（application/json）として送られます。

$response = Http::post('https://example.com/users', [
    'name' => 'Taylor',
    'role' => 'admin',
]);

GET のクエリは、第2引数の配列か withQueryParameters で渡せます。

$response = Http::get('https://example.com/users', [
    'page' => 1,
]);

フォーム形式（application/x-www-form-urlencoded）にしたいときは、リクエスト前に asForm() を呼びます。

$response = Http::asForm()->post('https://example.com/users', [
    'name' => 'Taylor',
]);

---

ヘッダーと認証

カスタムヘッダーは withHeaders で付けます。期待するレスポンス種別には accept / acceptJson があります。

$response = Http::withHeaders([
    'X-First' => 'foo',
])->acceptJson()->get('https://example.com/users');

Bearer トークンは withToken($token) です。Basic / Digest 認証には withBasicAuth / withDigestAuth があります。

$response = Http::withToken('your-api-token')->get('https://example.com/user');

---

タイムアウト

timeout($seconds) は、レスポンスを待つ上限です。既定は 30 秒で、超えると Illuminate\Http\Client\ConnectionException が投げられます。接続確立の上限は connectTimeout($seconds) で、既定は 10 秒です。

$response = Http::timeout(5)->get('https://example.com/users');
$response = Http::connectTimeout(3)->get('https://example.com/users');

---

レスポンスの見方

返ってきた Response から、本文やステータスを調べられます。

メソッド	用途
body()	生の本文文字列
json($key = null, $default = null)	JSON を配列（または指定キー）として取得
status()	HTTP ステータスコード
successful()	200 番台（>= 200 かつ < 300）
failed()	400 以上
clientError() / serverError()	4xx / 5xx
header / headers	レスポンスヘッダー

if ($response->successful()) {
    $users = $response->json();
    $name = $response->json('name');
}

Illuminate\Http\Client\Response は ArrayAccess を実装しているので、JSON のフィールドを $response['name'] のようにも読めます。便利な真偽値として ok()（200）、created()（201）、notFound()（404）などもあります。

---

エラー処理

Guzzle の既定とは違い、Laravel の HTTP クライアントは 4xx / 5xx でも自動では例外を投げません。まず successful() / failed() / clientError() / serverError() で判定します。

例外にしたいときは throw() を使います。クライアント／サーバーエラー時に Illuminate\Http\Client\RequestException が投げられます。エラーがなければ throw() はレスポンス自身を返すので、チェーンできます。条件付きなら throwIf($condition) です。

$response = Http::post('https://example.com/users', ['name' => 'Taylor'])
    ->throw()
    ->json();

Http::get('https://example.com/users')->throwIf(fn ($response) => $response->status() === 422);

---

リトライ（短く）

一時的な失敗に備え、retry($times, $sleepMilliseconds) で自動リトライできます。クライアント／サーバーエラー時に再試行します。オプションの when コールバックや throw: false もドキュメントにあります。

$response = Http::retry(3, 100)->get('https://example.com/users');

---

テスト（短く）

テストでは Http::fake() で外向きリクエストをスタブできます。URL パターン（* ワイルドカード可）に Http::response(...) を割り当てます。送信内容の確認には Http::assertSent（一致するリクエストが1件以上あったこと）を使います。assertNotSent / assertSentCount / assertNothingSent もあります。

use Illuminate\Support\Facades\Http;

Http::fake([
    'example.com/*' => Http::response(['name' => 'Taylor'], 200),
]);

$response = Http::acceptJson()->get('https://example.com/users/1');

$response->successful(); // true
$response->json('name'); // Taylor

Http::assertSent(function ($request) {
    return $request->url() === 'https://example.com/users/1'
        && $request->hasHeader('Accept', 'application/json');
});

---

並列リクエスト（任意・最小）

複数リクエストをまとめて送るには Http::pool を使います。名前付きにする場合は $pool->as('name')->get(...) です。

use Illuminate\Http\Client\Pool;

$responses = Http::pool(fn (Pool $pool) => [
    $pool->as('users')->get('https://example.com/users'),
    $pool->as('posts')->get('https://example.com/posts'),
]);

$responses['users']->ok();
$responses['posts']->ok();

---

まとめ

• Laravel の HTTP クライアントは、外向きリクエスト用の Guzzle ラッパ（Http ファサード）
• get / post などで送り、POST 系の配列は既定で JSON。フォームは asForm()
• ヘッダーは withHeaders、Bearer は withToken。タイムアウト既定は 30 秒（接続は 10 秒）
• 4xx / 5xx では自動 throw しない。必要なら throw / throwIf
• テストは Http::fake と assertSent が入口

---

参考リンク

• Laravel 13.x HTTP Client
• Laravel 13.x Release Notes