#はじめに
Laravel は表現力豊かでシンプルな API を Guzzle HTTP client の上に提供し、他のウェブアプリケーションと通信するための外部 HTTP リクエストを素早く送信できます。Laravel の Guzzle ラッパーは、最も一般的なユースケースに焦点を当て、優れた開発者体験を提供します。
始める前に、Guzzle パッケージがアプリケーションの依存関係としてインストールされていることを確認してください。デフォルトでは、Laravel はこの依存関係を自動的に含みます。ただし、以前にパッケージを削除している場合は、Composer を使って再インストールできます:
composer require guzzlehttp/guzzle
#リクエストの送信
リクエストを送信するには、Http ファサードが提供する head、get、post、put、patch、delete メソッドを使います。まずは、別の URL に対して基本的な GET リクエストを送る方法を見てみましょう:
use Illuminate\Support\Facades\Http;
$response = Http::get('http://example.com');
get メソッドは Illuminate\Http\Client\Response のインスタンスを返し、このレスポンスを検査するための様々なメソッドを提供します:
$response->body() : string;
$response->json($key = null, $default = null) : array|mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->status() : int;
$response->successful() : bool;
$response->redirect(): bool;
$response->failed() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;
Illuminate\Http\Client\Response オブジェクトは PHP の ArrayAccess インターフェイスも実装しているため、JSON レスポンスのデータに直接アクセスできます:
return Http::get('http://example.com/users/1')['name'];
上記のレスポンスメソッドに加え、レスポンスが特定のステータスコードかどうかを判定するために以下のメソッドも使えます:
$response->ok() : bool; // 200 OK
$response->created() : bool; // 201 Created
$response->accepted() : bool; // 202 Accepted
$response->noContent() : bool; // 204 No Content
$response->movedPermanently() : bool; // 301 Moved Permanently
$response->found() : bool; // 302 Found
$response->badRequest() : bool; // 400 Bad Request
$response->unauthorized() : bool; // 401 Unauthorized
$response->paymentRequired() : bool; // 402 Payment Required
$response->forbidden() : bool; // 403 Forbidden
$response->notFound() : bool; // 404 Not Found
$response->requestTimeout() : bool; // 408 Request Timeout
$response->conflict() : bool; // 409 Conflict
$response->unprocessableEntity() : bool; // 422 Unprocessable Entity
$response->tooManyRequests() : bool; // 429 Too Many Requests
$response->serverError() : bool; // 500 Internal Server Error
#URI テンプレート
HTTP クライアントは URI テンプレート仕様 を使ってリクエスト URL を構築できます。URI テンプレートで展開可能な URL パラメータは withUrlParameters メソッドで定義できます:
Http::withUrlParameters([
'endpoint' => 'https://laravel.com',
'page' => 'docs',
'version' => '9.x',
'topic' => 'validation',
])->get('{+endpoint}/{page}/{version}/{topic}');
#リクエストのダンプ
送信前のリクエストインスタンスをダンプしてスクリプトの実行を停止したい場合は、リクエスト定義の先頭に dd メソッドを追加してください:
return Http::dd()->get('http://example.com');
#リクエストデータ
POST、PUT、PATCH リクエストで追加データを送信することは一般的で、これらのメソッドは第2引数にデータの配列を受け取ります。デフォルトではデータは application/json コンテンツタイプで送信されます:
use Illuminate\Support\Facades\Http;
$response = Http::post('http://example.com/users', [
'name' => 'Steve',
'role' => 'Network Administrator',
]);
#GET リクエストのクエリパラメータ
GET リクエストでは、URL に直接クエリ文字列を追加するか、get メソッドの第2引数にキーと値の配列を渡せます:
$response = Http::get('http://example.com/users', [
'name' => 'Taylor',
'page' => 1,
]);
または、withQueryParameters メソッドを使うこともできます:
Http::retry(3, 100)->withQueryParameters([
'name' => 'Taylor',
'page' => 1,
])->get('http://example.com/users')
#フォーム URL エンコードされたリクエストの送信
application/x-www-form-urlencoded コンテンツタイプでデータを送信したい場合は、リクエスト前に asForm メソッドを呼び出してください:
$response = Http::asForm()->post('http://example.com/users', [
'name' => 'Sara',
'role' => 'Privacy Consultant',
]);
#生のリクエストボディの送信
リクエスト時に生のリクエストボディを指定したい場合は withBody メソッドを使います。コンテンツタイプは第2引数で指定できます:
$response = Http::withBody(
base64_encode($photo), 'image/jpeg'
)->post('http://example.com/photo');
#マルチパートリクエスト
ファイルをマルチパートリクエストとして送信したい場合は、リクエスト前に attach メソッドを呼び出します。このメソッドはファイル名と内容を受け取ります。必要に応じて第3引数にファイル名、第4引数にファイルに関連するヘッダーを指定できます:
$response = Http::attach(
'attachment', file_get_contents('photo.jpg'), 'photo.jpg', ['Content-Type' => 'image/jpeg']
)->post('http://example.com/attachments');
ファイルの生の内容を渡す代わりに、ストリームリソースを渡すこともできます:
$photo = fopen('photo.jpg', 'r');
$response = Http::attach(
'attachment', $photo, 'photo.jpg'
)->post('http://example.com/attachments');
#ヘッダー
ヘッダーはwithHeadersメソッドを使用してリクエストに追加できます。withHeadersメソッドはキー/値のペアの配列を受け取ります:
$response = Http::withHeaders([
'X-First' => 'foo',
'X-Second' => 'bar'
])->post('http://example.com/users', [
'name' => 'Taylor',
]);
accept メソッドを使うと、リクエストに対して期待するレスポンスのコンテンツタイプを指定できます:
$response = Http::accept('application/json')->get('http://example.com/users');
便利な acceptJson メソッドを使うと、application/json コンテンツタイプを簡単に指定できます:
$response = Http::acceptJson()->get('http://example.com/users');
withHeaders メソッドは既存のヘッダーに新しいヘッダーをマージします。すべてのヘッダーを完全に置き換えたい場合は、replaceHeaders メソッドを使えます:
$response = Http::withHeaders([
'X-Original' => 'foo',
])->replaceHeaders([
'X-Replacement' => 'bar',
])->post('http://example.com/users', [
'name' => 'Taylor',
]);
#認証
withBasicAuth と withDigestAuth メソッドを使って、それぞれベーシック認証とダイジェスト認証の資格情報を指定できます:
// ベーシック認証...
$response = Http::withBasicAuth('[email protected]', 'secret')->post(/* ... */);
// ダイジェスト認証...
$response = Http::withDigestAuth('[email protected]', 'secret')->post(/* ... */);
#ベアラートークン
リクエストの Authorization ヘッダーにベアラートークンを素早く追加したい場合は、withToken メソッドを使います:
$response = Http::withToken('token')->post(/* ... */);
#タイムアウト
timeout メソッドでレスポンスを待つ最大秒数を指定できます。デフォルトでは 30 秒でタイムアウトします:
$response = Http::timeout(3)->get(/* ... */);
指定したタイムアウトを超えると、Illuminate\Http\Client\ConnectionException のインスタンスがスローされます。
connectTimeout メソッドでサーバーへの接続を試みる最大秒数を指定できます:
$response = Http::connectTimeout(3)->get(/* ... */);
#リトライ
クライアントまたはサーバーエラーが発生した場合に HTTP クライアントが自動的にリトライするようにしたい場合は、retry メソッドを使います。retry メソッドはリクエストを試行する最大回数と、試行間の待機ミリ秒数を受け取ります:
$response = Http::retry(3, 100)->post(/* ... */);
試行間の待機ミリ秒数を手動で計算したい場合は、retry メソッドの第2引数にクロージャを渡せます:
use Exception;
$response = Http::retry(3, function (int $attempt, Exception $exception) {
return $attempt * 100;
})->post(/* ... */);
便利な使い方として、retry メソッドの第1引数に配列を渡すこともできます。この配列は試行間の待機ミリ秒数を決定するために使われます:
$response = Http::retry([100, 200])->post(/* ... */);
必要に応じて、retry メソッドの第3引数にリトライを実際に行うかどうかを判定するコールバックを渡せます。例えば、最初のリクエストが ConnectionException に遭遇した場合のみリトライしたい場合などです:
use Exception;
use Illuminate\Http\Client\PendingRequest;
$response = Http::retry(3, 100, function (Exception $exception, PendingRequest $request) {
return $exception instanceof ConnectionException;
})->post(/* ... */);
リクエスト試行が失敗した場合に、新しい試行前にリクエストを変更したいことがあります。これは retry メソッドに渡したコールバックのリクエスト引数を変更することで実現できます。例えば、最初の試行で認証エラーが返った場合に新しい認証トークンでリトライするケースです:
use Exception;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\RequestException;
$response = Http::withToken($this->getToken())->retry(2, 0, function (Exception $exception, PendingRequest $request) {
if (! $exception instanceof RequestException || $exception->response->status() !== 401) {
return false;
}
$request->withToken($this->getNewToken());
return true;
})->post(/* ... */);
すべてのリクエストが失敗した場合、Illuminate\Http\Client\RequestException のインスタンスがスローされます。この挙動を無効にしたい場合は、throw 引数に false を指定してください。無効化すると、すべてのリトライ後に最後のレスポンスが返されます:
$response = Http::retry(3, 100, throw: false)->post(/* ... */);
すべてのリクエストが接続問題で失敗した場合、throw 引数が false に設定されていても Illuminate\Http\Client\ConnectionException はスローされます。
#エラーハンドリング
Guzzle のデフォルト動作とは異なり、Laravel の HTTP クライアントラッパーはクライアントまたはサーバーエラー(サーバーからの 400 または 500 レベルのレスポンス)で例外をスローしません。これらのエラーが返されたかどうかは、successful、clientError、serverError メソッドで判定できます:
// ステータスコードが 200 以上 300 未満か判定...
$response->successful();
// ステータスコードが 400 以上か判定...
$response->failed();
// 400 レベルのステータスコードか判定...
$response->clientError();
// 500 レベルのステータスコードか判定...
$response->serverError();
// クライアントまたはサーバーエラーが発生した場合に、指定したコールバックを即座に実行します...
$response->onError(callable $callback);
#例外のスロー
レスポンスインスタンスがあり、レスポンスのステータスコードがクライアントまたはサーバーエラーを示す場合に Illuminate\Http\Client\RequestException のインスタンスをスローしたい場合は、throw または throwIf メソッドを使えます。
use Illuminate\Http\Client\Response;
$response = Http::post(/* ... */);
// クライアントまたはサーバーエラーが発生した場合に例外をスローします...
$response->throw();
// エラーが発生し、指定した条件が真の場合に例外をスローします...
$response->throwIf($condition);
// エラーが発生し、指定したクロージャが真を返す場合に例外をスローします...
$response->throwIf(fn (Response $response) => true);
// エラーが発生し、指定した条件が偽の場合に例外をスローします...
$response->throwUnless($condition);
// エラーが発生し、指定したクロージャが偽を返す場合に例外をスローします...
$response->throwUnless(fn (Response $response) => false);
// レスポンスが特定のステータスコードの場合に例外をスローします...
$response->throwIfStatus(403);
// レスポンスが特定のステータスコードでない場合に例外をスローします...
$response->throwUnlessStatus(200);
return $response['user']['id'];
Illuminate\Http\Client\RequestException インスタンスは公開された $response プロパティを持ち、返されたレスポンスを検査できます。
throw メソッドはエラーがなければレスポンスインスタンスを返すため、throw メソッドに続けて他の操作をチェーンできます。
return Http::post(/* ... */)->throw()->json();
例外がスローされる前に追加の処理を行いたい場合は、throw メソッドにクロージャを渡せます。クロージャ実行後に例外は自動的にスローされるため、クロージャ内で再スローする必要はありません。
use Illuminate\Http\Client\Response;
use Illuminate\Http\Client\RequestException;
return Http::post(/* ... */)->throw(function (Response $response, RequestException $e) {
// ...
})->json();
#Guzzle ミドルウェア
Laravel の HTTP クライアントは Guzzle を利用しているため、Guzzle ミドルウェア を使って送信リクエストの操作や受信レスポンスの検査ができます。送信リクエストを操作するには、withRequestMiddleware メソッドで Guzzle ミドルウェアを登録します。
use Illuminate\Support\Facades\Http;
use Psr\Http\Message\RequestInterface;
$response = Http::withRequestMiddleware(
function (RequestInterface $request) {
return $request->withHeader('X-Example', 'Value');
}
)->get('http://example.com');
同様に、withResponseMiddleware メソッドでミドルウェアを登録して受信 HTTP レスポンスを検査できます。
use Illuminate\Support\Facades\Http;
use Psr\Http\Message\ResponseInterface;
$response = Http::withResponseMiddleware(
function (ResponseInterface $response) {
$header = $response->getHeader('X-Example');
// ...
return $response;
}
)->get('http://example.com');
#グローバルミドルウェア
すべての送信リクエストと受信レスポンスに適用されるミドルウェアを登録したい場合は、globalRequestMiddleware と globalResponseMiddleware メソッドを使います。通常はアプリケーションの AppServiceProvider の boot メソッド内で呼び出します。
use Illuminate\Support\Facades\Http;
Http::globalRequestMiddleware(fn ($request) => $request->withHeader(
'User-Agent', 'Example Application/1.0'
));
Http::globalResponseMiddleware(fn ($response) => $response->withHeader(
'X-Finished-At', now()->toDateTimeString()
));
#Guzzle オプション
withOptions メソッドで追加の Guzzle リクエストオプション を指定できます。withOptions はキーと値の配列を受け取ります。
$response = Http::withOptions([
'debug' => true,
])->get('http://example.com/users');
#同時リクエスト
複数の HTTP リクエストを同時に実行したい場合があります。つまり、リクエストを順番に送るのではなく、同時に複数送信します。遅い HTTP API とやり取りする際に大幅なパフォーマンス向上が期待できます。
pool メソッドを使うとこれを実現できます。pool は Illuminate\Http\Client\Pool インスタンスを受け取るクロージャを受け取り、リクエストプールに簡単にリクエストを追加して送信できます。
use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;
$responses = Http::pool(fn (Pool $pool) => [
$pool->get('http://localhost/first'),
$pool->get('http://localhost/second'),
$pool->get('http://localhost/third'),
]);
return $responses[0]->ok() &&
$responses[1]->ok() &&
$responses[2]->ok();
ご覧の通り、各レスポンスインスタンスはプールに追加した順番でアクセスできます。必要に応じて as メソッドでリクエストに名前を付け、名前で対応するレスポンスにアクセスできます。
use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;
$responses = Http::pool(fn (Pool $pool) => [
$pool->as('first')->get('http://localhost/first'),
$pool->as('second')->get('http://localhost/second'),
$pool->as('third')->get('http://localhost/third'),
]);
return $responses['first']->ok();
#同時リクエストのカスタマイズ
pool メソッドは withHeaders や middleware など他の HTTP クライアントメソッドとチェーンできません。プール内のリクエストにカスタムヘッダーやミドルウェアを適用したい場合は、各リクエストでそれらのオプションを設定してください。
use Illuminate\Http\Client\Pool;
use Illuminate\Support\Facades\Http;
$headers = [
'X-Example' => 'example',
];
$responses = Http::pool(fn (Pool $pool) => [
$pool->withHeaders($headers)->get('http://laravel.test/test'),
$pool->withHeaders($headers)->get('http://laravel.test/test'),
$pool->withHeaders($headers)->get('http://laravel.test/test'),
]);
#マクロ
Laravel の HTTP クライアントは「マクロ」を定義でき、アプリケーション全体で共通のリクエストパスやヘッダーを設定するための流暢で表現力豊かな仕組みを提供します。始めるには、アプリケーションの App\Providers\AppServiceProvider クラスの boot メソッド内でマクロを定義します。
use Illuminate\Support\Facades\Http;
/**
* アプリケーションサービスを起動します。
*/
public function boot(): void
{
Http::macro('github', function () {
return Http::withHeaders([
'X-Example' => 'example',
])->baseUrl('https://github.com');
});
}
マクロを設定したら、アプリケーションのどこからでも呼び出して指定した設定の保留中リクエストを作成できます。
$response = Http::github()->get('/');
#テスト
多くの Laravel サービスはテストを簡単かつ表現力豊かに書くための機能を提供しており、Laravel の HTTP クライアントも例外ではありません。Http ファサードの fake メソッドを使うと、リクエスト時にスタブ/ダミーレスポンスを返すよう指示できます。
#レスポンスのフェイク
例えば、すべてのリクエストに対して空の 200 ステータスコードレスポンスを返すよう HTTP クライアントに指示するには、引数なしで fake メソッドを呼びます。
use Illuminate\Support\Facades\Http;
Http::fake();
$response = Http::post(/* ... */);
#特定の URL のフェイク
または、fake メソッドに配列を渡せます。配列のキーはフェイクしたい URL パターン、値は対応するレスポンスです。* はワイルドカードとして使えます。フェイクされていない URL へのリクエストは実際に実行されます。Http ファサードの response メソッドでこれらのエンドポイント用のスタブ/フェイクレスポンスを作成できます。
Http::fake([
// GitHub エンドポイント用の JSON レスポンスをスタブします...
'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),
// Google エンドポイント用の文字列レスポンスをスタブします...
'google.com/*' => Http::response('Hello World', 200, $headers),
]);
マッチしないすべての URL をスタブするフォールバック URL パターンを指定したい場合は、単一の * 文字を使えます。
Http::fake([
// GitHub エンドポイント用の JSON レスポンスをスタブします...
'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),
// その他すべてのエンドポイント用の文字列レスポンスをスタブします...
'*' => Http::response('Hello World', 200, ['Headers']),
]);
#レスポンスシーケンスのフェイク
単一の URL が特定の順序で複数のフェイクレスポンスを返す必要がある場合があります。Http::sequence メソッドを使ってレスポンスを構築できます。
Http::fake([
// GitHub エンドポイント用のレスポンスの一連をスタブします...
'github.com/*' => Http::sequence()
->push('Hello World', 200)
->push(['foo' => 'bar'], 200)
->pushStatus(404),
]);
レスポンスシーケンスのすべてのレスポンスが消費されると、それ以降のリクエストは例外をスローします。シーケンスが空の場合に返すデフォルトレスポンスを指定したい場合は、whenEmpty メソッドを使います。
Http::fake([
// GitHub エンドポイント用のレスポンスの一連をスタブします...
'github.com/*' => Http::sequence()
->push('Hello World', 200)
->push(['foo' => 'bar'], 200)
->whenEmpty(Http::response()),
]);
特定の URL パターンを指定せずにレスポンスシーケンスをフェイクしたい場合は、Http::fakeSequence メソッドを使えます。
Http::fakeSequence()
->push('Hello World', 200)
->whenEmpty(Http::response());
#フェイクコールバック
特定のエンドポイントに返すレスポンスを決定するためにより複雑なロジックが必要な場合は、fake メソッドにクロージャを渡せます。このクロージャは Illuminate\Http\Client\Request インスタンスとオプションの配列を受け取り、レスポンスインスタンスを返す必要があります。クロージャ内で必要なロジックを実行して返すレスポンスを決定できます。
use Illuminate\Http\Client\Request;
Http::fake(function (Request $request, array $options) {
return Http::response('Hello World', 200);
});
#迷子リクエストの防止
HTTP クライアント経由で送信されるすべてのリクエストがテスト内またはテストスイート全体でフェイクされていることを保証したい場合は、preventStrayRequests メソッドを呼びます。このメソッドを呼んだ後、対応するフェイクレスポンスがないリクエストは実際の HTTP リクエストを送る代わりに例外をスローします。
use Illuminate\Support\Facades\Http;
Http::preventStrayRequests();
Http::fake([
'github.com/*' => Http::response('ok'),
]);
// "ok" レスポンスが返されます...
Http::get('https://github.com/laravel/framework');
// 例外がスローされます...
Http::get('https://laravel.com');
#リクエストの検査
レスポンスをフェイクしているときに、アプリケーションが正しいデータやヘッダーを送信しているか確認したい場合があります。Http::fake の後に Http::assertSent メソッドを呼ぶことでこれを実現できます。
assertSent メソッドはクロージャを受け取り、そのクロージャは Illuminate\Http\Client\Request インスタンスを受け取ってリクエストが期待通りかどうかを示す真偽値を返す必要があります。テストが成功するには、少なくとも1つのリクエストが期待に合致している必要があります。
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
Http::fake();
Http::withHeaders([
'X-First' => 'foo',
])->post('http://example.com/users', [
'name' => 'Taylor',
'role' => 'Developer',
]);
Http::assertSent(function (Request $request) {
return $request->hasHeader('X-First', 'foo') &&
$request->url() == 'http://example.com/users' &&
$request['name'] == 'Taylor' &&
$request['role'] == 'Developer';
});
必要に応じて、assertNotSent メソッドを使って特定のリクエストが送信されなかったことを検証できます。
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
Http::fake();
Http::post('http://example.com/users', [
'name' => 'Taylor',
'role' => 'Developer',
]);
Http::assertNotSent(function (Request $request) {
return $request->url() === 'http://example.com/posts';
});
テスト中に「送信された」リクエストの数を検証するには、assertSentCount メソッドを使えます。
Http::fake();
Http::assertSentCount(5);
または、テスト中にリクエストが一切送信されなかったことを検証するには、assertNothingSent メソッドを使えます。
Http::fake();
Http::assertNothingSent();
#リクエスト / レスポンスの記録
recorded メソッドを使うと、すべてのリクエストとそれに対応するレスポンスを取得できます。recorded メソッドは、Illuminate\Http\Client\Request と Illuminate\Http\Client\Response のインスタンスを含む配列のコレクションを返します。
Http::fake([
'https://laravel.com' => Http::response(status: 500),
'https://nova.laravel.com/' => Http::response(),
]);
Http::get('https://laravel.com');
Http::get('https://nova.laravel.com/');
$recorded = Http::recorded();
[$request, $response] = $recorded[0];
さらに、recorded メソッドはクロージャを受け取ることができ、そのクロージャは Illuminate\Http\Client\Request と Illuminate\Http\Client\Response のインスタンスを受け取り、期待に応じてリクエスト/レスポンスのペアをフィルタリングできます。
use Illuminate\Http\Client\Request;
use Illuminate\Http\Client\Response;
Http::fake([
'https://laravel.com' => Http::response(status: 500),
'https://nova.laravel.com/' => Http::response(),
]);
Http::get('https://laravel.com');
Http::get('https://nova.laravel.com/');
$recorded = Http::recorded(function (Request $request, Response $response) {
return $request->url() !== 'https://laravel.com' &&
$response->successful();
});
#イベント
Laravel は HTTP リクエスト送信の過程で3つのイベントを発火します。RequestSending イベントはリクエスト送信前に発火し、ResponseReceived イベントはレスポンス受信後に発火します。ConnectionFailed イベントはリクエストに対してレスポンスが受信できなかった場合に発火します。
RequestSending と ConnectionFailed イベントはどちらも、Illuminate\Http\Client\Request インスタンスを検査できる公開 $request プロパティを持ちます。同様に、ResponseReceived イベントは $request プロパティに加え、Illuminate\Http\Client\Response インスタンスを検査できる $response プロパティも持ちます。これらのイベントリスナーは App\Providers\EventServiceProvider サービスプロバイダーで登録できます。
/**
* アプリケーションのイベントリスナーのマッピング。
*
* @var array
*/
protected $listen = [
'Illuminate\Http\Client\Events\RequestSending' => [
'App\Listeners\LogRequestSending',
],
'Illuminate\Http\Client\Events\ResponseReceived' => [
'App\Listeners\LogResponseReceived',
],
'Illuminate\Http\Client\Events\ConnectionFailed' => [
'App\Listeners\LogConnectionFailed',
],
];