Laravel 11.x HTTPクライアント

イントロダクションIntroduction

Laravelは、Guzzle HTTPクライアントの周りに表現力豊かで最小限のAPIを提供し、他のWebアプリケーションと通信するための外部HTTPリクエストをすばやく作成できるようにします。LaravelによるGuzzleのラッパーは、最も一般的なユースケースと素晴らしい開発者エクスペリエンスに焦点を当てています。Laravel provides an expressive, minimal API around the Guzzle HTTP client[http://docs.guzzlephp.org/en/stable/], allowing you to quickly make outgoing HTTP requests to communicate with other web applications. Laravel's wrapper around Guzzle is focused on its most common use cases and a wonderful developer experience.

リクエストの作成Making Requests

リクエストを行うには、Httpファサードが提供するhead、get、post、put、patch、deleteメソッドを使用します。まず、外部のURLに対して基本的なGETリクエストを行う方法を見てみましょう。To make requests, you may use the head, get, post, put, patch, and delete methods provided by the Http facade. First, let's examine how to make a basic GET request to another URL:

use Illuminate\Support\Facades\Http;

$response = Http::get('http://example.com');

getメソッドはIlluminate\Http\Client\Responseのインスタンスを返します。これは、レスポンスを調べるために使用できるさまざまなメソッドを提供します。The get method returns an instance of Illuminate\Http\Client\Response, which provides a variety of methods that may be used to inspect the 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レスポンスデータへ直接アクセスできます。The Illuminate\Http\Client\Response object also implements the PHP ArrayAccess interface, allowing you to access JSON response data directly on the response:

return Http::get('http://example.com/users/1')['name'];

上記レスポンスメソッドに加え、以下のメソッドにより、レスポンスが特定のステータスコードを持つか判断できます。In addition to the response methods listed above, the following methods may be used to determine if the response has a given status code:

$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テンプレートURI Templates

HTTPクライアントは、URIテンプレート仕様を用いて、リクエストURLを構築することも可能です。URIテンプレートで展開できるURLパラメータを定義するには、withUrlParametersメソッドを使用します。The HTTP client also allows you to construct request URLs using the URI template specification[https://www.rfc-editor.org/rfc/rfc6570]. To define the URL parameters that can be expanded by your URI template, you may use the withUrlParameters method:

Http::withUrlParameters([
    'endpoint' => 'https://laravel.com',
    'page' => 'docs',
    'version' => '11.x',
    'topic' => 'validation',
])->get('{+endpoint}/{page}/{version}/{topic}');

リクエストのダンプDumping Requests

送信するリクエストインスタンスを送信して、スクリプトの実行を終了する前にダンプしたい場合は、リクエスト定義の先頭にddメソッドを追加できます。If you would like to dump the outgoing request instance before it is sent and terminate the script's execution, you may add the dd method to the beginning of your request definition:

return Http::dd()->get('http://example.com');

リクエストデータRequest Data

もちろん、POST、PUT、PATCHリクエストを作成するときは、リクエストとともに追加のデータを送信するのが一般的であるため、これらのメソッドは２番目の引数としてデータの配列を受け入れます。デフォルトでデータはapplication/jsonコンテンツタイプを使用して送信されます。Of course, it is common when making POST, PUT, and PATCH requests to send additional data with your request, so these methods accept an array of data as their second argument. By default, data will be sent using the application/json content type:

use Illuminate\Support\Facades\Http;

$response = Http::post('http://example.com/users', [
    'name' => 'Steve',
    'role' => 'Network Administrator',
]);

GETリクエストクエリパラメータGET Request Query Parameters

GETリクエストを行うときは、クエリ文字列をURLに直接追加するか、キー／値ペアの配列をgetメソッドの２番目の引数として渡せます。When making GET requests, you may either append a query string to the URL directly or pass an array of key / value pairs as the second argument to the get method:

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

あるいは、withQueryParametersメソッドを使うこともできます。Alternatively, the withQueryParameters method may be used:

Http::retry(3, 100)->withQueryParameters([
    'name' => 'Taylor',
    'page' => 1,
])->get('http://example.com/users')

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

application/x-www-form-urlencodedコンテンツタイプを使用してデータを送信する場合は、リクエストを行う前にasFormメソッドを呼び出す必要があります。If you would like to send data using the application/x-www-form-urlencoded content type, you should call the asForm method before making your request:

$response = Http::asForm()->post('http://example.com/users', [
    'name' => 'Sara',
    'role' => 'Privacy Consultant',
]);

素のリクエスト本文の送信Sending a Raw Request Body

リクエストを行うときに素のリクエスト本文を指定する場合は、withBodyメソッドを使用できます。コンテンツタイプは、メソッドの２番目の引数を介して提供できます。You may use the withBody method if you would like to provide a raw request body when making a request. The content type may be provided via the method's second argument:

$response = Http::withBody(
    base64_encode($photo), 'image/jpeg'
)->post('http://example.com/photo');

マルチパートリクエストMulti-Part Requests

ファイルをマルチパートリクエストとして送信する場合は、リクエストを行う前にattachメソッドを呼び出す必要があります。このメソッドは、ファイルの名前とその内容を引数に取ります。必要に応じて、ファイルの名前と見なす３番目の引数を指定できます。また、第４引数は、ファイルに関連するヘッダを指定するために使います。If you would like to send files as multi-part requests, you should call the attach method before making your request. This method accepts the name of the file and its contents. If needed, you may provide a third argument which will be considered the file's filename, while a fourth argument may be used to provide headers associated with the file:

$response = Http::attach(
    'attachment', file_get_contents('photo.jpg'), 'photo.jpg', ['Content-Type' => 'image/jpeg']
)->post('http://example.com/attachments');

ファイルの素の内容を渡す代わりに、ストリームリソースを渡すこともできます。Instead of passing the raw contents of a file, you may pass a stream resource:

$photo = fopen('photo.jpg', 'r');

$response = Http::attach(
    'attachment', $photo, 'photo.jpg'
)->post('http://example.com/attachments');

ヘッダHeaders

ヘッダは、withHeadersメソッドを使用してリクエストに追加できます。このwithHeadersメソッドは、キー／値ペアの配列を引数に取ります。Headers may be added to requests using the withHeaders method. This withHeaders method accepts an array of key / value pairs:

$response = Http::withHeaders([
    'X-First' => 'foo',
    'X-Second' => 'bar'
])->post('http://example.com/users', [
    'name' => 'Taylor',
]);

acceptメソッドを使って、アプリケーションがリクエストへのレスポンスとして期待するコンテンツタイプを指定できます。You may use the accept method to specify the content type that your application is expecting in response to your request:

$response = Http::accept('application/json')->get('http://example.com/users');

利便性のため、acceptJsonメソッドを使って、アプリケーションがリクエストへのレスポンスとしてapplication/jsonコンテンツタイプを期待することを素早く指定できます。For convenience, you may use the acceptJson method to quickly specify that your application expects the application/json content type in response to your request:

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

withHeadersメソッドは、新しいヘッダをリクエストの既存のヘッダへマージします。必要であれば、replaceHeadersメソッドを使用し、すべてのヘッダを完全に置き換えることもできます。The withHeaders method merges new headers into the request's existing headers. If needed, you may replace all of the headers entirely using the replaceHeaders method:

$response = Http::withHeaders([
    'X-Original' => 'foo',
])->replaceHeaders([
    'X-Replacement' => 'bar',
])->post('http://example.com/users', [
    'name' => 'Taylor',
]);

認証Authentication

基本認証のログイン情報とダイジェスト認証ログイン情報は、それぞれwithBasicAuthメソッドとwithDigestAuthメソッドを使用して指定します。You may specify basic and digest authentication credentials using the withBasicAuth and withDigestAuth methods, respectively:

// BASIC認証
$response = Http::withBasicAuth('taylor@laravel.com', 'secret')->post(/* ... */);

// ダイジェスト認証
$response = Http::withDigestAuth('taylor@laravel.com', 'secret')->post(/* ... */);

BearerトークンBearer Tokens

リクエストのAuthorizationヘッダにBearerトークンをすばやく追加したい場合は、withTokenメソッドを使用できます。If you would like to quickly add a bearer token to the request's Authorization header, you may use the withToken method:

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

タイムアウトTimeout

timeoutメソッドを使用して、レスポンスを待機する最大秒数を指定できます。デフォルトでは、３０秒をすぎるとHTTPクライアントはタイム・アウトします。The timeout method may be used to specify the maximum number of seconds to wait for a response. By default, the HTTP client will timeout after 30 seconds:

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

指定したタイムアウトを超えると、Illuminate\Http\Client\ConnectionExceptionインスタンスを投げます。If the given timeout is exceeded, an instance of Illuminate\Http\Client\ConnectionException will be thrown.

サーバへの接続を試みる最長待ち秒数をconnectTimeoutメソッドで指定できます。You may specify the maximum number of seconds to wait while trying to connect to a server using the connectTimeout method:

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

再試行Retries

クライアントまたはサーバのエラーが発生した場合に、HTTPクライアントがリクエストを自動的に再試行するようにしたい場合は、retryメソッドを使用します。retryメソッドは、リクエストを試行する最大回数とLaravelが試行の間に待機するミリ秒数を引数に取ります。If you would like the HTTP client to automatically retry the request if a client or server error occurs, you may use the retry method. The retry method accepts the maximum number of times the request should be attempted and the number of milliseconds that Laravel should wait in between attempts:

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

試行間にスリープするミリ秒数を手作業で計算したい場合は、retryメソッドの第２引数へクロージャを渡してください。If you would like to manually calculate the number of milliseconds to sleep between attempts, you may pass a closure as the second argument to the retry method:

use Exception;

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

使いやすいように、retryメソッドの第１引数へ配列を指定することもできます。この配列は、次の試行までの間に何ミリ秒スリープするか決めるために使われます。For convenience, you may also provide an array as the first argument to the retry method. This array will be used to determine how many milliseconds to sleep between subsequent attempts:

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

必要であれば、retryメソッドに第３引数を渡せます。第３引数には、実際に再試行を行うかどうかを決定するCallableを指定します。例えば、最初のリクエストでConnectionExceptionが発生した場合にのみ、リクエストを再試行したいとしましょう。If needed, you may pass a third argument to the retry method. The third argument should be a callable that determines if the retries should actually be attempted. For example, you may wish to only retry the request if the initial request encounters an ConnectionException:

use Exception;
use Illuminate\Http\Client\PendingRequest;

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

リクエストの試行に失敗した場合、新しく試みる前にリクエストへ変更を加えたい場合があります。これを実現するには、retryメソッドに渡すコールバックのrequest引数を変更します。例えば、最初の試行が認証エラーを返した場合、新しい認証トークンを使ってリクエストを再試行したいと思います。If a request attempt fails, you may wish to make a change to the request before a new attempt is made. You can achieve this by modifying the request argument provided to the callable you provided to the retry method. For example, you might want to retry the request with a new authorization token if the first attempt returned an authentication error:

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を指定してください。無効にすると、すべての再試行のあと、クライアントが最後に受信したレスポンスを返します。If all of the requests fail, an instance of Illuminate\Http\Client\RequestException will be thrown. If you would like to disable this behavior, you may provide a throw argument with a value of false. When disabled, the last response received by the client will be returned after all retries have been attempted:

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

warning Warning! 接続の問題ですべてのリクエストが失敗した場合は、throw引数をfalseに設定していてもIlluminate\Http\Client\ConnectionExceptionが投げられます。[!WARNING]
If all of the requests fail because of a connection issue, a Illuminate\Http\Client\ConnectionException will still be thrown even when the throw argument is set to false.

エラー処理Error Handling

Guzzleのデフォルト動作とは異なり、LaravelのHTTPクライアントラッパーは、クライアントまたはサーバのエラー(サーバからの「400」および「500」レベルの応答)で例外を投げません。successful、clientError、serverErrorメソッドを使用して、これらのエラーのいずれかが返されたかどうかを判定できます。Unlike Guzzle's default behavior, Laravel's HTTP client wrapper does not throw exceptions on client or server errors (400 and 500 level responses from servers). You may determine if one of these errors was returned using the successful, clientError, or serverError methods:

// ステータスコードが200以上300未満か判定
$response->successful();

// ステータスコードが400以上か判定
$response->failed();

// レスポンスに400レベルのステータスコードがあるかを判定
$response->clientError();

// レスポンスに500レベルのステータスコードがあるかを判定
$response->serverError();

// クライアントまたはサーバエラーが発生した場合、指定コールバックを即座に実行
$response->onError(callable $callback);

例外を投げるThrowing Exceptions

あるレスポンスインスタンスのレスポンスステータスコードがクライアントまたはサーバのエラーを示している場合にIlluminate\Http\Client\RequestExceptionのインスタンスを投げたい場合場合は、throwかthrowIfメソッドを使用します。If you have a response instance and would like to throw an instance of Illuminate\Http\Client\RequestException if the response status code indicates a client or server error, you may use the throw or throwIf methods:

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プロパティがあり、返ってきたレスポンスを検査できます。The Illuminate\Http\Client\RequestException instance has a public $response property which will allow you to inspect the returned response.

throwメソッドは、エラーが発生しなかった場合にレスポンスインスタンスを返すので、他の操作をthrowメソッドにチェーンできます。The throw method returns the response instance if no error occurred, allowing you to chain other operations onto the throw method:

return Http::post(/* ... */)->throw()->json();

例外がなげられる前に追加のロジックを実行したい場合は、throwメソッドにクロージャを渡せます。クロージャを呼び出した後に、例外を自動的に投げるため、クロージャ内から例外を再発行する必要はありません。If you would like to perform some additional logic before the exception is thrown, you may pass a closure to the throw method. The exception will be thrown automatically after the closure is invoked, so you do not need to re-throw the exception from within the closure:

use Illuminate\Http\Client\Response;
use Illuminate\Http\Client\RequestException;

return Http::post(/* ... */)->throw(function (Response $response, RequestException $e) {
    // ...
})->json();

GuzzleミドルウェアGuzzle Middleware

LaravelのHTTPクライアントはGuzzleで動いているので、Guzzleミドルウェアを利用して、送信するリクエストの操作や受信したレスポンスの検査ができます。送信リクエストを操作するには、withRequestMiddlewareでGuzzleミドルウェアを登録します。Since Laravel's HTTP client is powered by Guzzle, you may take advantage of Guzzle Middleware[https://docs.guzzlephp.org/en/stable/handlers-and-middleware.html] to manipulate the outgoing request or inspect the incoming response. To manipulate the outgoing request, register a Guzzle middleware via the withRequestMiddleware method:

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レスポンスを検査できます。Likewise, you can inspect the incoming HTTP response by registering a middleware via the withResponseMiddleware method:

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

グローバルミドルウェアGlobal Middleware

時には、すべての送信リクエストと受信レスポンスへ適用するミドルウェアを登録したいこともあるでしょう。それには、globalRequestMiddlewareメソッドとglobalResponseMiddlewareメソッドを使います。通常、これらのメソッドはアプリケーションのAppServiceProviderで、bootメソッドから呼び出す必要があります。Sometimes, you may want to register a middleware that applies to every outgoing request and incoming response. To accomplish this, you may use the globalRequestMiddleware and globalResponseMiddleware methods. Typically, these methods should be invoked in the boot method of your application's AppServiceProvider:

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オプションGuzzle Options

withOptionsメソッドを使用すると、送信リクエストへ追加のGuzzleリクエストオプションを指定できます。withOptionsメソッドはキーと値のペアの配列を引数に取ります：You may specify additional Guzzle request options[http://docs.guzzlephp.org/en/stable/request-options.html] for an outgoing request using the withOptions method. The withOptions method accepts an array of key / value pairs:

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

グローバルオプションGlobal Options

すべての送信リクエストに対してデフォルトのオプションを設定するには、globalOptionsメソッドを利用します。通常、このメソッドはアプリケーションのAppServiceProviderのbootメソッドから呼び出します。To configure default options for every outgoing request, you may utilize the globalOptions method. Typically, this method should be invoked from the boot method of your application's AppServiceProvider:

use Illuminate\Support\Facades\Http;

/**
 * 全アプリケーションサービスの初期起動処理
 */
public function boot(): void
{
    Http::globalOptions([
        'allow_redirects' => false,
    ]);
}

同時リクエストConcurrent Requests

複数のHTTPリクエストを同時に実行したい場合があります。言い換えれば、複数のリクエストを順番に発行するのではなく、同時にディスパッチしたい状況です。これにより、低速なHTTP APIを操作する際のパフォーマンスが大幅に向上します。Sometimes, you may wish to make multiple HTTP requests concurrently. In other words, you want several requests to be dispatched at the same time instead of issuing the requests sequentially. This can lead to substantial performance improvements when interacting with slow HTTP APIs.

さいわいに、poolメソッドを使い、これを実現できます。poolメソッドは、Illuminate\Http\Client\Poolインスタンスを受け取るクロージャを引数に取り、簡単にリクエストプールにリクエストを追加してディスパッチできます。Thankfully, you may accomplish this using the pool method. The pool method accepts a closure which receives an Illuminate\Http\Client\Pool instance, allowing you to easily add requests to the request pool for dispatching:

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メソッドを使い、リクエストに名前を付けると、対応するレスポンスへ名前でアクセスできるようになります。As you can see, each response instance can be accessed based on the order it was added to the pool. If you wish, you can name the requests using the as method, which allows you to access the corresponding responses by name:

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

現在のリクエストのカスタマイズCustomizing Concurrent Requests

poolメソッドは、withHeadersやmiddlewareメソッドのような、他のHTTPクライアントメソッドとチェーンできません。プールしたリクエストへカスタムヘッダやミドルウェアを適用したい場合は、プール内の各リクエストでそれらのオプションを設定する必要があります。The pool method cannot be chained with other HTTP client methods such as the withHeaders or middleware methods. If you want to apply custom headers or middleware to pooled requests, you should configure those options on each request in the pool:

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'),
]);

マクロMacros

LaravelのHTTPクライアントでは、「マクロ」を定義可能です。マクロは、アプリケーション全体でサービスとやり取りする際に、共通のリクエストパスやヘッダを設定するために、流暢で表現力のあるメカニズムとして機能します。利用するには、アプリケーションの App\Providers\AppServiceProviderクラスのbootメソッド内で、マクロを定義します。The Laravel HTTP client allows you to define "macros", which can serve as a fluent, expressive mechanism to configure common request paths and headers when interacting with services throughout your application. To get started, you may define the macro within the boot method of your application's App\Providers\AppServiceProvider class:

use Illuminate\Support\Facades\Http;

/**
 * 全アプリケーションサービスの初期起動処理
 */
public function boot(): void
{
    Http::macro('github', function () {
        return Http::withHeaders([
            'X-Example' => 'example',
        ])->baseUrl('https://github.com');
    });
}

マクロを設定したら、アプリケーションのどこからでもマクロを呼び出し、保留中のリクエストを指定した設定で作成できます。Once your macro has been configured, you may invoke it from anywhere in your application to create a pending request with the specified configuration:

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

テストTesting

Laravelの多くのサービスでは、テストを簡単かつ表現豊かに書くための機能を提供しており、HTTPクライアントも例外ではありません。Httpファサードのfakeメソッドにより、リクエストが行われたときにスタブ/ダミーレスポンスを返すようにHTTPクライアントに指示できます。Many Laravel services provide functionality to help you easily and expressively write tests, and Laravel's HTTP client is no exception. The Http facade's fake method allows you to instruct the HTTP client to return stubbed / dummy responses when requests are made.

レスポンスのfakeFaking Responses

たとえば、リクエストごとに空の200ステータスコードレスポンスを返すようにHTTPクライアントに指示するには、引数なしでfakeメソッドを呼びだしてください。For example, to instruct the HTTP client to return empty, 200 status code responses for every request, you may call the fake method with no arguments:

use Illuminate\Support\Facades\Http;

Http::fake();

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

特定のURLのfakeFaking Specific URLs

もしくは、配列をfakeメソッドに渡すこともできます。配列のキーは、fakeしたいURLパターンとそれに関連するレスポンスを表す必要があります。*文字はワイルドカード文字として使用できます。FakeしないURLに対して行うリクエストは、実際に実行されます。Httpファサードのresponseメソッドを使用して、これらのエンドポイントのスタブ/fakeのレスポンスを作成できます。Alternatively, you may pass an array to the fake method. The array's keys should represent URL patterns that you wish to fake and their associated responses. The * character may be used as a wildcard character. Any requests made to URLs that have not been faked will actually be executed. You may use the Http facade's response method to construct stub / fake responses for these endpoints:

Http::fake([
    // GitHubエンドポイントのJSONレスポンスをスタブ
    'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),

    // Googleエンドポイントの文字列レスポンスをスタブ
    'google.com/*' => Http::response('Hello World', 200, $headers),
]);

一致しないすべてのURLをスタブするフォールバックURLパターンを指定する場合は、単一の*文字を使用します。If you would like to specify a fallback URL pattern that will stub all unmatched URLs, you may use a single * character:

Http::fake([
    // GitHubエンドポイントのJSONレスポンスをスタブ
    'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),

    // 他のすべてのエンドポイントの文字列をスタブ
    '*' => Http::response('Hello World', 200, ['Headers']),
]);

利便上、単純な文字列、JSON、空のレスポンスは、レスポンスとして文字列、配列、整数を指定することで生成できます。For convenience, simple string, JSON, and empty responses may be generated by providing a string, array, or integer as the response:

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

接続例外のfakeFaking Connection Exceptions

HTTPクライアントがリクエストしようとしたときに、Illuminate\Http\Client\ConnectionExceptionが発生したときの、アプリケーション動作をテストする必要があるかもしれません。failedConnectionメソッドを使用して、HTTPクライアントへ接続例外を投げるよう指示できます。Sometimes you may need to test your application's behavior if the HTTP client encounters an Illuminate\Http\Client\ConnectionException when attempting to make a request. You can instruct the HTTP client to throw a connection exception using the failedConnection method:

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

fakeレスポンスの順番Faking Response Sequences

場合によっては、単一のURLが特定の順序で一連のfakeレスポンスを返すように指定する必要があります。これは、Http::sequenceメソッドを使用してレスポンスを作成することで実現できます。Sometimes you may need to specify that a single URL should return a series of fake responses in a specific order. You may accomplish this using the Http::sequence method to build the responses:

Http::fake([
    // GitHubエンドポイントの一連のレスポンスをスタブ
    'github.com/*' => Http::sequence()
                            ->push('Hello World', 200)
                            ->push(['foo' => 'bar'], 200)
                            ->pushStatus(404),
]);

レスポンスシーケンス内のすべてのレスポンスが消費されると、以降のリクエストに対し、レスポンスシーケンスは例外を投げます。シーケンスが空になったときに返すデフォルトのレスポンスを指定する場合は、whenEmptyメソッドを使用します。When all the responses in a response sequence have been consumed, any further requests will cause the response sequence to throw an exception. If you would like to specify a default response that should be returned when a sequence is empty, you may use the whenEmpty method:

Http::fake([
    // GitHubエンドポイントの一連のレスポンスをスタブ
    'github.com/*' => Http::sequence()
                            ->push('Hello World', 200)
                            ->push(['foo' => 'bar'], 200)
                            ->whenEmpty(Http::response()),
]);

一連のレスポンスをfakeしたいが、fakeする必要がある特定のURLパターンを指定する必要がない場合は、Http::fakeSequenceメソッドを使用します。If you would like to fake a sequence of responses but do not need to specify a specific URL pattern that should be faked, you may use the Http::fakeSequence method:

Http::fakeSequence()
        ->push('Hello World', 200)
        ->whenEmpty(Http::response());

FakeコールバックFake Callback

特定のエンドポイントに対して返すレスポンスを決定するために、より複雑なロジックが必要な場合は、fakeメソッドにクロージャを渡すことができます。このクロージャはIlluminate\Http\Client\Requestインスタンスを受け取り、レスポンスインスタンスを返す必要があります。クロージャ内で、返すレスポンスのタイプを決定するために必要なロジックを実行できます。If you require more complicated logic to determine what responses to return for certain endpoints, you may pass a closure to the fake method. This closure will receive an instance of Illuminate\Http\Client\Request and should return a response instance. Within your closure, you may perform whatever logic is necessary to determine what type of response to return:

use Illuminate\Http\Client\Request;

Http::fake(function (Request $request) {
    return Http::response('Hello World', 200);
});

行き先がないリクエストの防止Preventing Stray Requests

HTTPクライアントから送信したすべてのリクエストを個々のテスト、またはテストスイート全体で確実にフェイクにしたい場合は、preventStrayRequestsメソッドをコールします。このメソッドを呼び出すと、対応するフェイクレスポンスがないリクエストは、実際にHTTPリクエストを行うのではなく、例外を投げるようになります。If you would like to ensure that all requests sent via the HTTP client have been faked throughout your individual test or complete test suite, you can call the preventStrayRequests method. After calling this method, any requests that do not have a corresponding fake response will throw an exception rather than making the actual HTTP request:

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

レスポンスの検査Inspecting Requests

レスポンスをfakeする場合、アプリケーションが正しいデータまたはヘッダを送信していることを確認するために、クライアントが受信するリクエストを調べたい場合があります。これは、Http::fakeを呼び出した後にHttp::assertSentメソッドを呼び出し実現します。When faking responses, you may occasionally wish to inspect the requests the client receives in order to make sure your application is sending the correct data or headers. You may accomplish this by calling the Http::assertSent method after calling Http::fake.

assertSentメソッドは、Illuminate\Http\Client\Requestインスタンスを受け取るクロージャを引数に受け、リクエストがエクスペクテーションに一致するかを示す論理値を返す必要があります。テストに合格するには、指定するエクスペクテーションに一致する少なくとも１つのリクエストが発行される必要があります。The assertSent method accepts a closure which will receive an Illuminate\Http\Client\Request instance and should return a boolean value indicating if the request matches your expectations. In order for the test to pass, at least one request must have been issued matching the given expectations:

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メソッドを使用して特定のリクエストが送信されないことを宣言できます。If needed, you may assert that a specific request was not sent using the assertNotSent method:

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メソッドを使用できます。You may use the assertSentCount method to assert how many requests were "sent" during the test:

Http::fake();

Http::assertSentCount(5);

または、assertNothingSentメソッドを使用して、テスト中にリクエストが送信されないことを宣言することもできます。Or, you may use the assertNothingSent method to assert that no requests were sent during the test:

Http::fake();

Http::assertNothingSent();

リクエスト／レスポンスの記録Recording Requests / Responses

すべてのリクエストと、それに対応するレスポンスを収集するために、recordedメソッドが使用できます。recordedメソッドは、Illuminate\Http\Client\RequestとIlluminate\Http\Client\Responseインスタンスを含む配列のコレクションを返します。You may use the recorded method to gather all requests and their corresponding responses. The recorded method returns a collection of arrays that contains instances of Illuminate\Http\Client\Request and 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インスタンスを受け取るクロージャを引数に取り、エクスペクテーションに基づいてリクエストとレスポンスのペアをフィルターするために使用できます。Additionally, the recorded method accepts a closure which will receive an instance of Illuminate\Http\Client\Request and Illuminate\Http\Client\Response and may be used to filter request / response pairs based on your expectations:

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

イベントEvents

LaravelはHTTPリクエストを送信する過程で、3つのイベントを発行します。RequestSendingイベントはリクエストが送信される前に発生し、ResponseReceivedイベントは指定したリクエストに対するレスポンスを受け取った後に発行します。ConnectionFailedイベントは、指定したリクエストに対するレスポンスを受信できなかった場合に発行します。Laravel fires three events during the process of sending HTTP requests. The RequestSending event is fired prior to a request being sent, while the ResponseReceived event is fired after a response is received for a given request. The ConnectionFailed event is fired if no response is received for a given request.

RequestSendingイベントとConnectionFailedイベントはどちらもpublicの$requestプロパティを持ち、これを使用してIlluminate\Http\Client\Requestインスタンスを調べられます。同様に、ResponseReceivedイベントには$requestプロパティと$responseプロパティがあり、これを使用してIlluminate\Http\Client\Responseインスタンスを調べられます。アプリケーション内で、こうしたイベントのイベントリスナを作成できます。The RequestSending and ConnectionFailed events both contain a public $request property that you may use to inspect the Illuminate\Http\Client\Request instance. Likewise, the ResponseReceived event contains a $request property as well as a $response property which may be used to inspect the Illuminate\Http\Client\Response instance. You may create event listeners[/docs/{{version}}/events] for these events within your application:

use Illuminate\Http\Client\Events\RequestSending;

class LogRequest
{
    /**
     * 指定イベントを処理する
     */
    public function handle(RequestSending $event): void
    {
        // $event->request …
    }
}