バージョン: 13.x

HTTPクライアント (HTTP Client)

Introduction
リクエストの作成
同時リクエスト
- リクエストプーリング
- リクエストのバッチ処理
Macros
Testing
Events

導入 (Introduction)

Laravel は、Guzzle HTTP クライアントを中心とした表現力豊かな最小限の API を提供し、他の Web アプリケーションと通信するための送信 HTTP リクエストを迅速に作成できるようにします。 Laravel の Guzzle のラッパーは、最も一般的なユースケースと素晴らしい開発者エクスペリエンスに重点を置いています。

リクエストの作成 (Making Requests)

リクエストを行うには、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) : mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->resource() : resource;
$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' => '13.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 に直接追加するか、キーと値のペアの配列を 2 番目の引数として get メソッドに渡すことができます。

$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 メソッドを使用して指定できます。

// Basic authentication...
$response = Http::withBasicAuth('[email protected]', 'secret')->post(/* ... */);

// Digest authentication...
$response = Http::withDigestAuth('[email protected]', 'secret')->post(/* ... */);

無記名トークン

リクエストの Authorization ヘッダーにベアラートークンをすぐに追加したい場合は、withToken メソッドを使用できます。

$response = Http::withToken('token')->post(/* ... */);

タイムアウト

timeout メソッドを使用して、応答を待機する最大秒数を指定できます。デフォルトでは、HTTP クライアントは 30 秒後にタイムアウトします。

$response = Http::timeout(3)->get(/* ... */);

指定されたタイムアウトを超えると、Illuminate\Http\Client\ConnectionException のインスタンスがスローされます。

connectTimeout メソッドを使用して、サーバーへの接続を試行するときに待機する最大秒数を指定できます。デフォルトは 10 秒です。

$response = Http::connectTimeout(3)->get(/* ... */);

再試行

クライアントまたはサーバーのエラーが発生した場合に HTTP クライアントがリクエストを自動的に再試行するようにしたい場合は、retry メソッドを使用できます。 retry メソッドは、リクエストを試行する最大回数と、Laravel が試行の間に待機するミリ秒数を受け入れます。

$response = Http::retry(3, 100)->post(/* ... */);

試行間のスリープ時間を手動で計算したい場合は、retry メソッドの 2 番目の引数としてクロージャを渡すことができます。

use Exception;

$response = Http::retry(3, function (int $attempt, Exception $exception) {
    return $attempt * 100;
})->post(/* ... */);

便宜上、retry メソッドの最初の引数として配列を指定することもできます。この配列は、次の試行の間にスリープする時間をミリ秒単位で決定するために使用されます。

$response = Http::retry([100, 200])->post(/* ... */);

必要に応じて、retry メソッドに 3 番目の引数を渡すことができます。 3 番目の引数は、実際に再試行するかどうかを決定する呼び出し可能引数である必要があります。たとえば、最初のリクエストで ConnectionException が発生した場合にのみリクエストを再試行したい場合があります。

use Illuminate\Http\Client\PendingRequest;
use Throwable;

$response = Http::retry(3, 100, function (Throwable $exception, PendingRequest $request) {
    return $exception instanceof ConnectionException;
})->post(/* ... */);

リクエストの試行が失敗した場合は、新たな試行を行う前にリクエストを変更することができます。これを実現するには、retry メソッドに指定した呼び出し可能オブジェクトに指定したリクエスト引数を変更します。たとえば、最初の試行で認証エラーが返された場合は、新しい認可トークンを使用してリクエストを再試行することができます。

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\RequestException;
use Throwable;

$response = Http::withToken($this->getToken())->retry(2, 0, function (Throwable $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 メソッドを使用して、これらのエラーのいずれかが返されたかどうかを確認できます。

// Determine if the status code is >= 200 and < 300...
$response->successful();

// Determine if the status code is >= 400...
$response->failed();

// Determine if the response has a 400 level status code...
$response->clientError();

// Determine if the response has a 500 level status code...
$response->serverError();

// Immediately execute the given callback if there was a client or server error...
$response->onError(callable $callback);

例外のスロー

応答インスタンスがあり、応答ステータスコードがクライアントエラーまたはサーバーエラーを示している場合に Illuminate\Http\Client\RequestException のインスタンスをスローしたい場合は、throw メソッドまたは throwIf メソッドを使用できます。

use Illuminate\Http\Client\Response;

$response = Http::post(/* ... */);

// Throw an exception if a client or server error occurred...
$response->throw();

// Throw an exception if an error occurred and the given condition is true...
$response->throwIf($condition);

// Throw an exception if an error occurred and the given closure resolves to true...
$response->throwIf(fn (Response $response) => true);

// Throw an exception if an error occurred and the given condition is false...
$response->throwUnless($condition);

// Throw an exception if an error occurred and the given closure resolves to false...
$response->throwUnless(fn (Response $response) => false);

// Throw an exception if the response has a specific status code...
$response->throwIfStatus(403);

// Throw an exception unless the response has a specific status code...
$response->throwUnlessStatus(200);

// Throw an exception if a server error occurred (status >500)...
$response->throwIfServerError();

// Throw an exception if a client error occurred (status >400 and <500)...
$response->throwIfClientError();

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();

デフォルトでは、RequestException メッセージはログに記録またはレポートされるときに 120 文字に切り詰められます。この動作をカスタマイズまたは無効にするには、bootstrap/app.php ファイルでアプリケーションの登録された動作を構成するときに、truncateAt メソッドと dontTruncate メソッドを利用できます。

use Illuminate\Http\Client\RequestException;

->registered(function (): void {
    // Truncate request exception messages to 240 characters...
    RequestException::truncateAt(240);

    // Disable request exception message truncation...
    RequestException::dontTruncate();
})

あるいは、truncateExceptionsAt メソッドを使用して、リクエストごとに例外切り捨て動作をカスタマイズすることもできます。

return Http::truncateExceptionsAt(240)->post(/* ... */);

ガズルミドルウェア

Laravel の HTTP クライアントは 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()
));

ガズルオプション

withOptions メソッドを使用して、送信リクエストに追加の Guzzle リクエストのオプションを指定できます。 withOptions メソッドは、キーと値のペアの配列を受け入れます。

$response = Http::withOptions([
    'debug' => true,
])->get('http://example.com/users');

グローバルオプション

すべての発信リクエストのデフォルトオプションを設定するには、globalOptions メソッドを利用できます。通常、このメソッドは、アプリケーションの AppServiceProvider の boot メソッドから呼び出す必要があります。

use Illuminate\Support\Facades\Http;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Http::globalOptions([
        'allow_redirects' => false,
    ]);
}

同時リクエスト (Concurrent Requests)

場合によっては、複数の 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();

リクエストプールの最大同時実行数は、concurrency 引数を pool メソッドに指定することで制御できます。この値により、リクエストプールの処理中に同時に実行できる HTTP リクエストの最大数が決まります。

$responses = Http::pool(fn (Pool $pool) => [
    // ...
], concurrency: 5);

同時リクエストのカスタマイズ

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 で同時リクエストを処理するもう 1 つの方法は、batch メソッドを使用することです。 pool メソッドと同様に、Illuminate\Http\Client\Batch インスタンスを受け取るクロージャを受け入れるため、ディスパッチするリクエストプールにリクエストを簡単に追加できますが、完了コールバックを定義することもできます。

use Illuminate\Http\Client\Batch;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;

$responses = Http::batch(fn (Batch $batch) => [
    $batch->get('http://localhost/first'),
    $batch->get('http://localhost/second'),
    $batch->get('http://localhost/third'),
])->before(function (Batch $batch) {
    // The batch has been created but no requests have been initialized...
})->progress(function (Batch $batch, int|string $key, Response $response) {
    // An individual request has completed successfully...
})->then(function (Batch $batch, array $results) {
    // All requests completed successfully...
})->catch(function (Batch $batch, int|string $key, Response|RequestException|ConnectionException $response) {
    // Batch request failure detected...
})->finally(function (Batch $batch, array $results) {
    // The batch has finished executing...
})->send();

pool メソッドと同様に、as メソッドを使用してリクエストに名前を付けることができます。

$responses = Http::batch(fn (Batch $batch) => [
    $batch->as('first')->get('http://localhost/first'),
    $batch->as('second')->get('http://localhost/second'),
    $batch->as('third')->get('http://localhost/third'),
])->send();

send メソッドを呼び出して batch を開始した後は、それに新しいリクエストを追加することはできません。これを実行しようとすると、Illuminate\Http\Client\BatchInProgressException 例外がスローされます。

リクエストバッチの最大同時実行数は、concurrency メソッドを介して制御できます。この値により、リクエストバッチの処理中に同時に実行できる HTTP リクエストの最大数が決まります。

$responses = Http::batch(fn (Batch $batch) => [
    // ...
])->concurrency(5)->send();

バッチの検査

バッチ完了コールバックに提供される Illuminate\Http\Client\Batch インスタンスには、特定のリクエストのバッチの操作と検査を支援するさまざまなプロパティとメソッドがあります。

// The number of requests assigned to the batch...
$batch->totalRequests;
 
// The number of requests that have not been processed yet...
$batch->pendingRequests;
 
// The number of requests that have failed...
$batch->failedRequests;

// The number of requests that have been processed thus far...
$batch->processedRequests();

// Indicates if the batch has finished executing...
$batch->finished();

// Indicates if the batch has request failures...
$batch->hasFailures();

バッチの延期

defer メソッドが呼び出されたとき、リクエストのバッチはすぐには実行されません。代わりに、Laravel は、現在のアプリケーションリクエストの HTTP 応答がユーザーに送信された後にバッチを実行し、アプリケーションの高速性と応答性を維持します。

use Illuminate\Http\Client\Batch;
use Illuminate\Support\Facades\Http;

$responses = Http::batch(fn (Batch $batch) => [
    $batch->get('http://localhost/first'),
    $batch->get('http://localhost/second'),
    $batch->get('http://localhost/third'),
])->then(function (Batch $batch, array $results) {
    // All requests completed successfully...
})->defer();

マクロ (Macros)

Laravel HTTP クライアントを使用すると、アプリケーション全体でサービスと対話するときに共通のリクエストパスとヘッダーを構成するための流暢で表現力豊かなメカニズムとして機能する「マクロ」を定義できます。まず、アプリケーションの App\Providers\AppServiceProvider クラスの boot メソッド内でマクロを定義します。

use Illuminate\Support\Facades\Http;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Http::macro('github', function () {
        return Http::withHeaders([
            'X-Example' => 'example',
        ])->baseUrl('https://github.com');
    });
}

マクロを構成したら、アプリケーション内のどこからでもマクロを呼び出して、指定された構成で保留中のリクエストを作成できます。

$response = Http::github()->get('/');

テスト (Testing)

多くの Laravel サービスは、テストを簡単かつ表現力豊かに作成できるようにする機能を提供しており、Laravel の HTTP クライアントも例外ではありません。 Http ファサードの fake メソッドを使用すると、リクエストが行われたときにスタブ/ダミー応答を返すように HTTP クライアントに指示できます。

偽装応答

たとえば、すべてのリクエストに対して空の 200 ステータスコード応答を返すように HTTP クライアントに指示するには、引数なしで fake メソッドを呼び出すことができます。

use Illuminate\Support\Facades\Http;

Http::fake();

$response = Http::post(/* ... */);

特定の URL を偽装する

あるいは、配列を fake メソッドに渡すこともできます。配列のキーは、偽装したい URL パターンとそれに関連する応答を表す必要があります。 * 文字はワイルドカード文字として使用できます。 Http ファサードの response メソッドを使用して、次のエンドポイントのスタブ/偽の応答を構築できます。

Http::fake([
    // Stub a JSON response for GitHub endpoints...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),

    // Stub a string response for Google endpoints...
    'google.com/*' => Http::response('Hello World', 200, $headers),
]);

偽装されていない URL に対して行われたリクエストはすべて実際に実行されます。一致しない URL をすべてスタブするフォールバック URL パターンを指定したい場合は、単一の * 文字を使用できます。

Http::fake([
    // Stub a JSON response for GitHub endpoints...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),

    // Stub a string response for all other endpoints...
    '*' => Http::response('Hello World', 200, ['Headers']),
]);

便宜上、文字列、配列、または整数を応答として指定することで、単純な文字列、JSON、および空の応答を生成できます。

Http::fake([
    'google.com/*' => 'Hello World',
    'github.com/*' => ['foo' => 'bar'],
    'chatgpt.com/*' => 200,
]);

例外の偽装

HTTP クライアントがリクエストを実行しようとしたときに Illuminate\Http\Client\ConnectionException を検出した場合、アプリケーションの動作をテストする必要がある場合があります。 failedConnection メソッドを使用して、HTTP クライアントに接続例外をスローするように指示できます。

Http::fake([
    'github.com/*' => Http::failedConnection(),
]);

Illuminate\Http\Client\RequestException がスローされた場合のアプリケーションの動作をテストするには、failedRequest メソッドを使用できます。

$this->mock(GithubService::class);
    ->shouldReceive('getUser')
    ->andThrow(
        Http::failedRequest(['code' => 'not_found'], 404)
    );

応答シーケンスの偽装

場合によっては、単一の URL が特定の順序で一連の偽の応答を返すように指定する必要がある場合があります。これは、Http::sequence メソッドを使用して応答を構築することで実現できます。

Http::fake([
    // Stub a series of responses for GitHub endpoints...
    'github.com/*' => Http::sequence()
        ->push('Hello World', 200)
        ->push(['foo' => 'bar'], 200)
        ->pushStatus(404),
]);

応答シーケンス内のすべての応答が消費されると、それ以上の要求によって応答シーケンスは例外をスローします。シーケンスが空の場合に返されるデフォルトの応答を指定したい場合は、whenEmpty メソッドを使用できます。

Http::fake([
    // Stub a series of responses for GitHub endpoints...
    '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) {
    return Http::response('Hello World', 200);
});

リクエストの検査

応答を偽装する場合、アプリケーションが正しいデータまたはヘッダーを送信していることを確認するために、クライアントが受信するリクエストを検査したい場合があります。これを行うには、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();
});

迷走リクエストの防止

HTTP クライアント経由で送信されたすべてのリクエストが個別のテストまたはテストスイート全体にわたって偽装されていることを確認したい場合は、preventStrayRequests メソッドを呼び出すことができます。このメソッドを呼び出した後、対応する偽の応答がないリクエストは、実際の HTTP リクエストを作成するのではなく、例外をスローします。

use Illuminate\Support\Facades\Http;

Http::preventStrayRequests();

Http::fake([
    'github.com/*' => Http::response('ok'),
]);

// An "ok" response is returned...
Http::get('https://github.com/laravel/framework');

// An exception is thrown...
Http::get('https://laravel.com');

場合によっては、特定のリクエストの実行を許可しながら、ほとんどの迷走リクエストを阻止したい場合があります。これを実現するには、URL パターンの配列を allowStrayRequests メソッドに渡すことができます。指定されたパターンのいずれかに一致するリクエストは許可されますが、他のすべてのリクエストは例外をスローし続けます。

use Illuminate\Support\Facades\Http;

Http::preventStrayRequests();

Http::allowStrayRequests([
    'http://127.0.0.1:5000/*',
]);

// This request is executed...
Http::get('http://127.0.0.1:5000/generate');

// An exception is thrown...
Http::get('https://laravel.com');

イベント (Events)

Laravel は、HTTP リクエストの送信プロセス中に 3 つのイベントを発生させます。 RequestSending イベントはリクエストが送信される前に発生しますが、ResponseReceived イベントは特定のリクエストに対する応答を受信した後に発生します。 ConnectionFailed イベントは、指定されたリクエストに対する応答が受信されない場合に発生します。

RequestSending イベントと ConnectionFailed イベントには両方とも、Illuminate\Http\Client\Request インスタンスの検査に使用できるパブリック $request プロパティが含まれています。同様に、ResponseReceived イベントには、$request プロパティと、Illuminate\Http\Client\Response インスタンスの検査に使用できる $response プロパティが含まれています。アプリケーション内で次のイベントに対してイベントリスナを作成できます。

use Illuminate\Http\Client\Events\RequestSending;

class LogRequest
{
    /**
     * Handle the event.
     */
    public function handle(RequestSending $event): void
    {
        // $event->request ...
    }
}

導入 (Introduction)​

リクエストの作成 (Making Requests)​

URI テンプレート​

ダンピングリクエスト​

データのリクエスト​

GETリクエストのクエリパラメータ​

フォーム URL エンコードされたリクエストの送信​

生のリクエスト本文の送信​

マルチパートリクエスト​

ヘッダー​

認証​

無記名トークン​

タイムアウト​

再試行​

エラー処理​

例外のスロー​

ガズルミドルウェア​

グローバルミドルウェア​

ガズルオプション​

グローバルオプション​

同時リクエスト (Concurrent Requests)​

リクエストプーリング​

同時リクエストのカスタマイズ​

リクエストのバッチ処理​

バッチの検査​

バッチの延期​

マクロ (Macros)​

テスト (Testing)​

偽装応答​

特定の URL を偽装する​

例外の偽装​

応答シーケンスの偽装​

偽のコールバック​

リクエストの検査​

リクエスト/レスポンスの記録​

迷走リクエストの防止​

イベント (Events)​

導入 (Introduction)

リクエストの作成 (Making Requests)

URI テンプレート

ダンピングリクエスト

データのリクエスト

GETリクエストのクエリパラメータ

フォーム URL エンコードされたリクエストの送信

生のリクエスト本文の送信

マルチパートリクエスト

ヘッダー

認証

無記名トークン

タイムアウト

再試行

エラー処理

例外のスロー

ガズルミドルウェア

グローバルミドルウェア

ガズルオプション

グローバルオプション

同時リクエスト (Concurrent Requests)

リクエストプーリング

同時リクエストのカスタマイズ

リクエストのバッチ処理

バッチの検査

バッチの延期

マクロ (Macros)

テスト (Testing)

偽装応答

特定の URL を偽装する

例外の偽装

応答シーケンスの偽装

偽のコールバック

リクエストの検査

リクエスト/レスポンスの記録

迷走リクエストの防止

イベント (Events)