Laravel 8.x HTTPクライアント

イントロダクション

Laravelは、Guzzle HTTPクライアントの周りに表現力豊かで最小限のAPIを提供し、他のWebアプリケーションと通信するための外部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) : array|mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->status() : int;
$response->ok() : bool;
$response->successful() : bool;
$response->redirect(): bool;
$response->failed() : bool;
$response->serverError() : 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'];

リクエストのダンプ

送信するリクエストインスタンスを送信して、スクリプトの実行を終了する前にダンプしたい場合は、リクエスト定義の先頭にddメソッドを追加できます。

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

リクエストデータ

もちろん、POST、PUT、PATCHリクエストを作成するときは、リクエストとともに追加のデータを送信するのが一般的であるため、これらのメソッドは２番目の引数としてデータの配列を受け入れます。デフォルトでデータはapplication/jsonコンテンツタイプを使用して送信されます。

use Illuminate\Support\Facades\Http;

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

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

GETリクエストを行うときは、クエリ文字列をURLに直接追加するか、キー／値ペアの配列をgetメソッドの２番目の引数として渡せます。

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

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

application/x-www-form-urlencodedコンテンツタイプを使用してデータを送信する場合は、リクエストを行う前にasFormメソッドを呼び出す必要があります。

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

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

リクエストを行うときに素のリクエスト本文を指定する場合は、withBodyメソッドを使用できます。コンテンツタイプは、メソッドの２番目の引数を介して提供できます。

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

マルチパートリクエスト

ファイルをマルチパートリクエストとして送信する場合は、リクエストを行う前にattachメソッドを呼び出す必要があります。このメソッドは、ファイルの名前とその内容を引数に取ります。必要に応じて、ファイルのファイル名と見なす３番目の引数を指定できます。

$response = Http::attach(
    'attachment', file_get_contents('photo.jpg'), 'photo.jpg'
)->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');

認証

基本認証のログイン情報とダイジェスト認証ログイン情報は、それぞれwithBasicAuthメソッドとwithDigestAuthメソッドを使用して指定します。

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

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

Bearerトークン

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

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

タイムアウト

timeoutメソッドを使用して、レスポンスを待機する最大秒数を指定できます。

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

指定したタイムアウトを超えると、Illuminate\Http\Client\ConnectionExceptionインスタンスを投げます。

再試行

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

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

必要であれば、retryメソッドに第３引数を渡せます。第３引数には、実際に再試行を行うかどうかを決定するCallableを指定します。例えば、最初のリクエストでConnectionExceptionが発生した場合にのみ、リクエストを再試行したいとしましょう。

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

すべてのリクエストが失敗した場合、Illuminate\Http\Client\RequestExceptionインスタンスを投げます。

エラー処理

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メソッドを使用します。

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

// クライアントまたはサーバのエラーが発生した場合は、例外を投げる
$response->throw();

// エラーが発生するか、指定条件が真の場合は、例外を投げる
$response->throwIf($condition);

return $response['user']['id'];

Illuminate\Http\Client\RequestExceptionインスタンスにはパブリック$responseプロパティがあり、返ってきたレスポンスを検査できます。

throwメソッドは、エラーが発生しなかった場合にレスポンスインスタンスを返すので、他の操作をthrowメソッドにチェーンできます。

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

例外がなげられる前に追加のロジックを実行したい場合は、throwメソッドにクロージャを渡せます。クロージャを呼び出した後に、例外を自動的に投げるため、クロージャ内から例外を再発行する必要はありません。

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

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

マクロ

LaravelのHTTPクライアントでは、「マクロ」を定義可能です。マクロは、アプリケーション全体でサービスとやり取りする際に、共通のリクエストパスやヘッダを設定するために、流暢で表現力のあるメカニズムとして機能します。利用するには、アプリケーションの App\Providers\AppServiceProviderクラスのbootメソッド内で、マクロを定義します。

use Illuminate\Support\Facades\Http;

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

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

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

テスト

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

レスポンスのfake

たとえば、リクエストごとに空の200ステータスコードレスポンスを返すようにHTTPクライアントに指示するには、引数なしでfakeメソッドを呼びだしてください。

use Illuminate\Support\Facades\Http;

Http::fake();

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

Note: リクエストをfakeする場合、HTTPクライアントミドルウェアは実行されません。これらのミドルウェアが正しく実行されたかのように、fakeレスポンスに対するエクスペクテーションを定義する必要があります。

特定のURLのfake

もしくは、配列をfakeメソッドに渡すこともできます。配列のキーは、fakeしたいURLパターンとそれに関連するレスポンスを表す必要があります。*文字はワイルドカード文字として使用できます。FakeしないURLに対して行うリクエストは、実際に実行されます。Httpファサードのresponseメソッドを使用して、これらのエンドポイントのスタブ/fakeのレスポンスを作成できます。

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

fakeレスポンスの順番

場合によっては、単一のURLが特定の順序で一連のfakeレスポンスを返すように指定する必要があります。これは、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()),
]);

一連のレスポンスをfakeしたいが、fakeする必要がある特定のURLパターンを指定する必要がない場合は、Http::fakeSequenceメソッドを使用します。

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

Fakeコールバック

特定のエンドポイントに対して返すレスポンスを決定するために、より複雑なロジックが必要な場合は、fakeメソッドにクロージャを渡すことができます。このクロージャはIlluminate\Http\Client\Requestインスタンスを受け取り、レスポンスインスタンスを返す必要があります。クロージャ内で、返すレスポンスのタイプを決定するために必要なロジックを実行できます。

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

レスポンスの検査

レスポンスをfakeする場合、アプリケーションが正しいデータまたはヘッダを送信していることを確認するために、クライアントが受信するリクエストを調べたい場合があります。これは、Http::fakeを呼び出した後にHttp::assertSentメソッドを呼び出し実現します。

assertSentメソッドは、Illuminate\Http\Client\Requestインスタンスを受け取るクロージャを引数に受け、リクエストがエクスペクテーションに一致するかを示す論理値を返す必要があります。テストに合格するには、指定するエクスペクテーションに一致する少なくとも１つのリクエストが発行される必要があります。

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

イベント

LaravelはHTTPリクエストを送信する過程で、3つのイベントを発行します。RequestSendingイベントはリクエストが送信される前に発生し、ResponseReceivedイベントは指定したリクエストに対するレスポンスを受け取った後に発行します。ConnectionFailedイベントは、指定したリクエストに対するレスポンスを受信できなかった場合に発行します。

RequestSendingとConnectionFailedイベントは両方とも、パブリックの$requestプロパティを含んでおり、これを使えばIlluminate\Http\Client\Requestインスタンスを調べられます。同様に、ResponseReceivedイベントは、$requestプロパティと$responseプロパティを含んでおり、Illuminate\Http\Client\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',
    ],
];