イントロダクション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.
使い始める前に、アプリケーションの依存関係としてGuzzleパッケージを確実にインストールしてください。デフォルトでLaravelはこの依存パッケージを自動的に含めます。もし、以前にパッケージを削除したことがある場合は、Composerを介して再度インストールしてください。Before getting started, you should ensure that you have installed the Guzzle package as a dependency of your application. By default, Laravel automatically includes this dependency. However, if you have previously removed the package, you may install it again via Composer:
composer require guzzlehttp/guzzle
リクエストの作成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) : 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レスポンスデータへ直接アクセスできます。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' => '9.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
リクエストを作成するときは、リクエストとともに追加のデータを送信するのが一般的であるため、これらのメソッドは2番目の引数としてデータの配列を受け入れます。デフォルトでデータは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
メソッドの2番目の引数として渡せます。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,
]);
フォーム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
メソッドを使用できます。コンテンツタイプは、メソッドの2番目の引数を介して提供できます。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
メソッドを呼び出す必要があります。このメソッドは、ファイルの名前とその内容を引数に取ります。必要に応じて、ファイルのファイル名と見なす3番目の引数を指定できます。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:
$response = Http::attach(
'attachment', file_get_contents('photo.jpg'), 'photo.jpg'
)->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');
認証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
メソッドを使用して、レスポンスを待機する最大秒数を指定できます。The timeout
method
may be used to specify the maximum number of seconds
to wait for a response:
$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
メソッドに第3引数を渡せます。第3引数には、実際に再試行を行うかどうかを決定する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
:
$response = Http::retry(3, 100, function ($exception, $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:
$response = Http::withToken($this->getToken())->retry(2, 0, function ($exception, $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! 接続の問題ですべてのリクエストが失敗した場合は、
throw
引数をfalse
に設定していてもIlluminate\Http\Client\ConnectionException
が投げられます。Warning
If all of the requests fail because of a connection issue, aIlluminate\Http\Client\ConnectionException
will still be thrown even when thethrow
argument is set tofalse
.
エラー処理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:
$response = Http::post(/* ... */);
// クライアントまたはサーバのエラーが発生した場合は、例外を投げる
$response->throw();
// エラーが発生し、指定条件が真の場合は、例外を投げる
$response->throwIf($condition);
// エラーが発生し、指定クロージャの結果が真の場合は例外を投げる
$response->throwIf(fn ($response) => true);
// エラーが発生し、指定条件が偽の場合は、例外を投げる
$response->throwUnless($condition);
// エラーが発生し、指定クロージャの結果が偽の場合は例外を投げる
$response->throwUnless(fn ($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:
return Http::post(/* ... */)->throw(function ($response, $e) {
//
})->json();
GuzzleミドルウェアGuzzle Middleware
LaravelのHTTPクライアントはGuzzleで動いているので、Guzzleミドルウェアを利用して、送信するリクエストの操作や受信したレスポンスの検査ができます。送信リクエストを操作するには、withMiddleware
メソッドとGuzzleのmapRequest
ミドルウェアファクトリを組み合わせて、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
withMiddleware
method in combination
with Guzzle's mapRequest
middleware
factory:
use GuzzleHttp\Middleware;
use Illuminate\Support\Facades\Http;
use Psr\Http\Message\RequestInterface;
$response = Http::withMiddleware(
Middleware::mapRequest(function (RequestInterface $request) {
$request = $request->withHeader('X-Example', 'Value');
return $request;
})
)->get('http://example.com');
同様に、GuzzleのmapResponse
ミドルウェアファクトリと組み合わせてwithMiddleware
メソッドをを登録すれば、受信HTTPレスポンスを検査できます。Likewise, you can inspect the
incoming HTTP response by registering a middleware
via the withMiddleware
method in
combination with Guzzle's mapResponse
middleware factory:
use GuzzleHttp\Middleware;
use Illuminate\Support\Facades\Http;
use Psr\Http\Message\ResponseInterface;
$response = Http::withMiddleware(
Middleware::mapResponse(function (ResponseInterface $response) {
$header = $response->getHeader('X-Example');
// ...
return $response;
})
)->get('http://example.com');
GuzzleオプションGuzzle Options
withOptions
メソッドを使用して、追加のGuzzleリクエストオプションを指定できます。withOptions
メソッドは、キー/値ペアの配列を引数に取ります。You may specify additional
Guzzle request
options[http://docs.guzzlephp.org/en/stable/request-options.html]
using the withOptions
method. The
withOptions
method accepts an array of
key / value pairs:
$response = Http::withOptions([
'debug' => true,
])->get('http://example.com/users');
同時リクエスト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();
マクロ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;
/**
* 全アプリケーションサービスの初期起動処理
*
* @return void
*/
public function boot()
{
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']),
]);
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
インスタンスを受け取るクロージャを引数に受け、リクエストがエクスペクテーションに一致するかを示す論理値を返す必要があります。テストに合格するには、指定するエクスペクテーションに一致する少なくとも1つのリクエストが発行される必要があります。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
イベントは両方とも、パブリックの$request
プロパティを含んでおり、これを使えばIlluminate\Http\Client\Request
インスタンスを調べられます。同様に、ResponseReceived
イベントは、$request
プロパティと$response
プロパティを含んでおり、Illuminate\Http\Client\Response
インスタンスの検査に使用できます。このイベントのイベントリスナは、App\Providers\EventServiceProvider
サービスプロバイダで登録します。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 register event listeners for this
event in your
App\Providers\EventServiceProvider
service provider:
/**
* アプリケーションのイベントリスナマップ
*
* @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',
],
];