HTTP 클라이언트

업데이트됨

번역일: 2026년 10월 2일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 10월 2일
번역 갱신: 2026년 10월 2일

HTTP 클라이언트

소개
요청 보내기
동시 요청
- 요청 풀링
- 요청 배칭
매크로
테스트
이벤트

소개

라라벨은 Guzzle HTTP 클라이언트를 감싼 간결하고 표현력 있는 API를 제공합니다. 이를 통해 다른 웹 애플리케이션과 통신하기 위한 HTTP 요청을 빠르게 작성할 수 있습니다. 외부 API와 연동하거나, 결제 서비스에 요청을 보내거나, 다른 서버의 데이터를 가져와야 할 때 라라벨의 HTTP 클라이언트가 개발자 경험을 한결 쾌적하게 만들어 줍니다.

NOTE

외부 서비스와 실제로 통신하지 않고도 애플리케이션 테스트를 작성할 수 있도록, 라라벨 HTTP 클라이언트는 요청을 손쉽게 "페이크"로 대체할 수 있는 기능도 제공합니다. 자세한 내용은 아래 테스트 섹션을 참고하세요.

예를 들어, 실제 결제 PG사(예: 국내 간편결제 서비스)나 알림톡 발송 API 같은 외부 서비스에 요청을 보내야 하는 상황을 떠올려 보세요. 매번 Guzzle을 직접 설정하는 대신, 라라벨의 Http 파사드를 사용하면 몇 줄만으로 요청을 보내고 응답을 다룰 수 있습니다.

요청 보내기

요청을 보내려면 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->serverError() : 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을 동적으로 구성할 수도 있습니다. withUrlParameters 메서드로 URI 템플릿에서 사용할 URL 파라미터를 정의해 보세요.

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

요청 덤프하기

요청을 전송하기 전에 해당 요청 인스턴스를 덤프하고 스크립트 실행을 즉시 종료하고 싶다면, 요청 정의의 맨 앞에 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' => '길동',
    'role' => '관리자',
]);

GET 요청의 쿼리 파라미터

GET 요청을 보낼 때는 URL에 직접 쿼리 문자열을 덧붙이거나, get 메서드의 두 번째 인자로 키 / 값 쌍의 배열을 전달할 수 있습니다.

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

또는 withQueryParameters 메서드를 사용할 수도 있습니다.

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

Form URL Encoded 요청 보내기

application/x-www-form-urlencoded 콘텐츠 타입으로 데이터를 전송하고 싶다면, 요청을 보내기 전에 asForm 메서드를 호출하면 됩니다.

$response = Http::asForm()->post('http://example.com/users', [
    'name' => '길동',
    'role' => '관리자',
]);

Raw 요청 본문 보내기

요청을 보낼 때 raw 형태의 요청 본문을 직접 지정하고 싶다면 withBody 메서드를 사용하세요. 콘텐츠 타입은 두 번째 인자로 지정할 수 있습니다.

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

Multi-Part 요청 보내기

요청을 멀티파트 형식으로 전송하고 싶다면(예: 파일 업로드), 요청 전에 attach 메서드를 호출합니다. 이 메서드는 파일의 이름과 내용을 인자로 받으며, 필요하다면 세 번째 인자로 파일명을 지정할 수도 있습니다. 네 번째 인자로는 파일과 관련된 헤더를 전달할 수 있습니다.

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

파일의 raw 내용을 직접 전달하는 대신, 스트림 리소스를 전달할 수도 있습니다.

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

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

헤더

withHeaders 메서드를 사용하면 요청에 헤더를 추가할 수 있습니다. 이 메서드는 키 / 값 쌍의 배열을 인자로 받습니다.

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

애플리케이션이 받고자 하는 콘텐츠 타입을 지정하려면 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' => 'value',
])->replaceHeaders([
    'X-Replacement' => 'value',
])->post('http://example.com/users', [
    'name' => '길동',
]);

인증

withBasicAuth와 withDigestAuth 메서드를 사용하면 각각 기본 인증(Basic Authentication)과 다이제스트 인증(Digest Authentication) 자격 증명을 지정할 수 있습니다.

// 기본 인증
$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 메서드를 사용하면 응답을 기다릴 최대 시간(초)을 지정할 수 있습니다. 기본적으로 HTTP 클라이언트는 30초 후 타임아웃됩니다.

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

지정한 타임아웃을 초과하면 Illuminate\Http\Client\ConnectionException 인스턴스가 발생(throw)됩니다.

서버에 연결을 시도하는 동안 기다릴 최대 시간(초)은 connectTimeout 메서드로 지정할 수 있습니다. 기본값은 10초입니다.

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

재시도

HTTP 클라이언트가 클라이언트 측 또는 서버 측 오류 발생 시 자동으로 재시도하도록 하고 싶다면 retry 메서드를 사용하세요. retry 메서드는 요청을 최대 몇 번까지 시도할지와, 각 시도 사이에 라라벨이 몇 밀리초를 기다려야 하는지를 인자로 받습니다.

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

각 재시도 사이의 대기 시간을 직접 계산하고 싶다면, retry 메서드의 두 번째 인자로 클로저를 전달할 수 있습니다.

use Exception;

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

편의를 위해, retry 메서드의 첫 번째 인자로 배열을 전달할 수도 있습니다. 이 배열은 각 시도 사이에 얼마나 대기할지를 결정하는 데 사용됩니다.

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

필요하다면, retry 메서드의 세 번째 인자로 콜러블을 전달해 실제로 재시도를 수행할지 여부를 결정할 수 있습니다. 예를 들어, 최초 요청이 ConnectionException을 만났을 때만 재시도하고 싶을 수 있습니다.

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

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

요청 시도가 실패하면, 다음 시도를 하기 전에 요청을 수정하고 싶을 수도 있습니다. 이는 retry 메서드에 제공한 콜러블로 전달받은 요청 인스턴스를 수정하는 방식으로 구현할 수 있습니다. 예를 들어, 최초 요청이 인증 에러를 반환했다면 새로운 인증 토큰으로 재시도하고 싶을 수 있습니다.

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

$response = Http::withToken($this->getToken())->retry(2, 0, function (Exception $exception, PendingRequest $request) {
    if (! $exception instanceof RequestException || $exception->response->status() !== 401) {
        return false;
    }

    $request->withToken($this->getNewToken());

    return true;
})->post(/* ... */);

모든 요청이 실패하면 Illuminate\Http\Client\RequestException 인스턴스가 발생합니다. 이 동작을 비활성화하고 싶다면 throw 인자를 false로 지정하세요. 비활성화하면 모든 재시도가 끝난 후 클라이언트가 받은 마지막 응답이 반환됩니다.

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

WARNING

모든 요청이 연결 문제로 인해 실패한 경우에는 throw 인자를 false로 설정하더라도 여전히 Illuminate\Http\Client\ConnectionException이 발생합니다.

에러 처리

Guzzle의 기본 동작과 달리, 라라벨 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();

// 에러가 발생했고 주어진 조건이 true이면 예외 발생시키기...
$response->throwIf($condition);

// 에러가 발생했고 주어진 클로저 결과가 true이면 예외 발생시키기...
$response->throwIf(fn (Response $response) => true);

// 에러가 발생했고 주어진 조건이 false이면 예외 발생시키기...
$response->throwUnless($condition);

// 에러가 발생했고 주어진 클로저 결과가 false이면 예외 발생시키기...
$response->throwUnless(fn (Response $response) => false);

// 응답이 특정 상태 코드를 가지고 있으면 예외 발생시키기...
$response->throwIfStatus(403);

// 응답이 특정 상태 코드를 가지고 있지 않으면 예외 발생시키기...
$response->throwUnlessStatus(200);

return $response->body();

Illuminate\Http\Client\RequestException 인스턴스는 $response 라는 public 프로퍼티를 가지고 있어서, 반환된 응답을 확인할 수 있습니다.

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 메시지는 로그에 기록하거나 보고할 때 128자로 잘립니다. 이 동작을 조정하거나 비활성화하고 싶다면, 애플리케이션의 bootstrap/app.php 파일에서 truncateRequestExceptionsAt 및 dontTruncateRequestExceptions 메서드를 사용할 수 있습니다.

->withExceptions(function (Exceptions $exceptions) {
    // 요청 예외 메시지를 240자로 자르기...
    $exceptions->truncateRequestExceptionsAt(240);

    // 요청 예외 메시지 자르기 비활성화...
    $exceptions->dontTruncateRequestExceptions();
})

Guzzle 미들웨어

라라벨 HTTP 클라이언트는 Guzzle을 기반으로 동작하므로, Guzzle 미들웨어를 활용해 발신 요청을 조작하거나 수신 응답을 검사할 수 있습니다. 발신 요청을 조작하려면, withRequestMiddleware 메서드로 Guzzle 미들웨어를 등록하세요.

use Illuminate\Http\Client\Request;

$response = Http::withRequestMiddleware(
    function (RequestInterface $request) {
        return $request->withHeader('X-Example', 'Value');
    }
)->get('http://example.com');

마찬가지로, withResponseMiddleware 메서드로 미들웨어를 등록해 수신되는 HTTP 응답을 검사할 수 있습니다.

use Illuminate\Http\Client\Response;
use Psr\Http\Message\ResponseInterface;

$response = Http::withResponseMiddleware(
    function (ResponseInterface $response) {
        $header = $response->getHeader('X-Example');

        // ...

        return $response;
    }
)->get('http://example.com');

전역 미들웨어

모든 발신 요청과 수신 응답에 적용되는 미들웨어를 등록하고 싶을 때가 있습니다. 모든 요청과 응답에 적용하려면 globalRequestMiddleware와 globalResponseMiddleware 메서드를 사용할 수 있습니다. 보통 이 메서드들은 애플리케이션의 AppServiceProvider의 boot 메서드에서 호출합니다.

use Illuminate\Support\Facades\Http;

Http::globalRequestMiddleware(fn ($request) => $request->withHeader(
    'User-Agent', 'Example Application/1.0'
));

Http::globalResponseMiddleware(fn ($response) => $response->withHeader(
    'X-Finished-At', now()->toDateTimeString()
));

Guzzle 옵션

withOptions 메서드를 사용하면 발신 요청에 추가적인 Guzzle 요청 옵션을 지정할 수 있습니다. withOptions 메서드는 키 / 값 쌍의 배열을 인자로 받습니다.

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

전역 옵션

모든 발신 요청에 대한 기본 옵션을 설정하고 싶다면 globalOptions 메서드를 사용할 수 있습니다. 일반적으로 이 메서드는 애플리케이션의 AppServiceProvider의 boot 메서드에서 호출합니다.

use Illuminate\Support\Facades\Http;

/**
 * 애플리케이션의 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Http::globalOptions([
        'allow_redirects' => false,
    ]);
}

HTTP 클라이언트

소개

Laravel은 Guzzle HTTP 클라이언트를 감싼 표현력 있고 간결한 API를 제공합니다. 이를 이용하면 다른 웹 애플리케이션과 통신하기 위한 외부 HTTP 요청을 빠르게 작성할 수 있습니다. Laravel이 Guzzle을 감싸는 방식은 가장 흔히 쓰이는 사용 사례에 초점을 맞추고 있으며, 사용하기 편한 개발 경험을 제공하는 데 중점을 두고 있습니다.

NOTE

이 문서는 Laravel의 HTTP 클라이언트 기능 중 핵심적인 부분을 다룹니다. 더 자세한 내용이 궁금하다면, Guzzle의 공식 문서인 Guzzle 문서를 함께 참고하는 것을 권장합니다.

HTTP 클라이언트

요청 보내기

Http 파사드가 제공하는 head, get, post, put, patch, delete 메서드를 사용하면 외부 서버로 HTTP 요청을 보낼 수 있습니다. 먼저 가장 기본적인 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, $flags = 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 요청을 보낼 때는 보통 추가 데이터를 함께 전송하게 되는데, 이런 메서드들은 두 번째 인자로 데이터 배열을 받습니다. 기본적으로 데이터는 application/json 콘텐츠 타입으로 전송됩니다:

use Illuminate\Support\Facades\Http;

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

GET 요청의 쿼리 파라미터

GET 요청을 보낼 때는 URL에 직접 쿼리 문자열을 붙이거나, get 메서드의 두 번째 인자로 key/value 배열을 전달할 수 있습니다:

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

Form URL Encoded 요청 보내기

application/x-www-form-urlencoded 콘텐츠 타입으로 데이터를 전송하고 싶다면, 요청 전에 asForm 메서드를 호출하면 됩니다:

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

Raw 요청 바디 보내기

요청 시 가공되지 않은 raw 바디를 직접 지정하고 싶다면 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', ['Content-Type' => 'image/jpeg']
)->post('http://example.com/attachments');

파일의 raw 콘텐츠를 직접 넘기는 대신, 스트림 리소스를 전달할 수도 있습니다:

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

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

헤더

요청에 헤더를 추가하려면 withHeaders 메서드를 사용합니다. 이 메서드는 key/value 쌍의 배열을 인자로 받습니다:

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

응답으로 application/json 콘텐츠 타입을 기대한다는 것을 간편하게 지정하고 싶다면 acceptJson 메서드를 사용할 수 있습니다:

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

withHeaders 메서드는 새로 지정한 헤더를 기존 헤더에 병합(merge)합니다. 만약 기존 헤더를 완전히 대체하고 싶다면 replaceHeaders 메서드를 사용하면 됩니다:

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

인증

기본 인증(Basic Authentication)과 다이제스트 인증(Digest Authentication)에 필요한 자격 증명은 각각 withBasicAuth, withDigestAuth 메서드로 지정할 수 있습니다:

// 기본 인증...
$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 메서드를 사용하면 응답을 기다리는 최대 시간(초)을 지정할 수 있습니다. 기본값은 30초이며, 이 시간이 지나면 타임아웃이 발생합니다:

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

지정한 타임아웃을 초과하면 Illuminate\Http\Client\ConnectionException 예외가 발생합니다.

서버에 연결을 시도할 때 기다릴 최대 시간(초)은 connectTimeout 메서드로 지정할 수 있습니다. 기본값은 10초입니다:

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

재시도

클라이언트 또는 서버 오류가 발생했을 때 HTTP 클라이언트가 자동으로 요청을 재시도하도록 하려면 retry 메서드를 사용하면 됩니다. retry 메서드는 최대 시도 횟수와, 시도 사이에 대기할 시간(밀리초)을 인자로 받습니다:

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

시도 간 대기 시간을 직접 계산하고 싶다면, retry 메서드의 두 번째 인자로 클로저를 전달할 수 있습니다:

use Exception;

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

편의상, retry 메서드의 첫 번째 인자로 배열을 전달할 수도 있습니다. 이 배열은 각 재시도 사이에 대기할 밀리초 값을 순서대로 정의합니다:

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

필요하다면 retry 메서드의 세 번째 인자로 콜러블(callable)을 전달할 수 있습니다. 이 콜러블은 실제로 재시도를 수행해야 하는지 여부를 결정합니다. 예를 들어, 최초 요청에서 ConnectionException이 발생했을 때만 재시도하고 싶다면 다음과 같이 작성할 수 있습니다:

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

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

요청 시도가 실패했을 때, 다음 시도 전에 요청 내용을 변경하고 싶을 수도 있습니다. 이 경우 retry 메서드에 전달한 콜러블의 $request 인자를 수정하면 됩니다. 예를 들어 첫 번째 시도에서 인증 오류가 반환되었다면, 새로운 인증 토큰으로 재시도하도록 만들 수 있습니다:

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(/* ... */);

WARNING

연결 문제로 인해 모든 요청이 실패한 경우에는 throw 인자를 false로 설정하더라도 Illuminate\Http\Client\ConnectionException은 여전히 발생합니다.

에러 처리

Guzzle의 기본 동작과는 달리, 라라벨의 HTTP 클라이언트 래퍼는 클라이언트 오류나 서버 오류(서버에서 반환하는 400번대, 500번대 응답)가 발생해도 예외를 던지지 않습니다. 이런 오류가 반환되었는지는 successful, clientError, serverError 메서드로 확인할 수 있습니다:

// 상태 코드가 200 이상 300 미만인지 확인...
$response->successful();

// 상태 코드가 400 이상인지 확인...
$response->failed();

// 400번대 상태 코드인지 확인...
$response->clientError();

// 500번대 상태 코드인지 확인...
$response->serverError();

// 클라이언트 오류 또는 서버 오류가 발생했을 때 즉시 주어진 콜백을 실행...
$response->onError(callable $callback);

예외 던지기

응답 인스턴스를 가지고 있고, 응답 상태 코드가 클라이언트 오류나 서버 오류를 나타낼 때 Illuminate\Http\Client\RequestException 예외를 던지고 싶다면 throw 또는 throwIf 메서드를 사용하면 됩니다:

use Illuminate\Http\Client\Response;

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

// 클라이언트 오류 또는 서버 오류가 발생했을 때 예외를 던짐...
$response->throw();

// 오류가 발생했고 주어진 조건이 true일 때 예외를 던짐...
$response->throwIf($condition);

// 오류가 발생했고 주어진 클로저의 결과가 true일 때 예외를 던짐...
$response->throwIf(fn (Response $response) => true);

// 오류가 발생했고 주어진 조건이 false일 때 예외를 던짐...
$response->throwUnless($condition);

// 오류가 발생했고 주어진 클로저의 결과가 false일 때 예외를 던짐...
$response->throwUnless(fn (Response $response) => false);

// 응답이 특정 상태 코드를 가질 때 예외를 던짐...
$response->throwIfStatus(403);

// 응답이 특정 상태 코드를 가지지 않을 때 예외를 던짐...
$response->throwUnlessStatus(200);

// 서버 오류가 발생했을 때(상태 코드 500 이상) 예외를 던짐...
$response->throwIfServerError();

// 클라이언트 오류가 발생했을 때(상태 코드 400 이상 500 미만) 예외를 던짐...
$response->throwIfClientError();

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

Illuminate\Http\Client\RequestException 인스턴스는 공개(public) 속성인 $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자로 잘립니다(truncate). 이 동작을 변경하거나 비활성화하려면, bootstrap/app.php 파일에서 애플리케이션의 등록(registered) 동작을 설정할 때 truncateAt과 dontTruncate 메서드를 사용하면 됩니다:

use Illuminate\Http\Client\RequestException;

->registered(function (): void {
    // 요청 예외 메시지를 240자로 자르도록 설정...
    RequestException::truncateAt(240);

    // 요청 예외 메시지 자르기 기능을 비활성화...
    RequestException::dontTruncate();
})

또는 요청 단위로 truncateExceptionsAt 메서드를 사용해서 예외 메시지 자르기 동작을 개별적으로 지정할 수도 있습니다:

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

Guzzle 미들웨어

라라벨의 HTTP 클라이언트는 내부적으로 Guzzle을 기반으로 동작하기 때문에, Guzzle 미들웨어를 활용해서 나가는 요청을 조작하거나 들어오는 응답을 검사할 수 있습니다. 나가는 요청을 조작하려면 withRequestMiddleware 메서드로 Guzzle 미들웨어를 등록하면 됩니다:

use Illuminate\Support\Facades\Http;
use Psr\Http\Message\RequestInterface;

$response = Http::withRequestMiddleware(
    function (RequestInterface $request) {
        return $request->withHeader('X-Example', 'Value');
    }
)->get('http://example.com');

마찬가지로, withResponseMiddleware 메서드로 미들웨어를 등록하면 들어오는 HTTP 응답도 검사할 수 있습니다:

use Illuminate\Support\Facades\Http;
use Psr\Http\Message\ResponseInterface;

$response = Http::withResponseMiddleware(
    function (ResponseInterface $response) {
        $header = $response->getHeader('X-Example');

        // ...

        return $response;
    }
)->get('http://example.com');

전역 미들웨어

경우에 따라 모든 나가는 요청과 들어오는 응답에 공통으로 적용되는 미들웨어를 등록하고 싶을 수도 있습니다. 이럴 때는 globalRequestMiddleware와 globalResponseMiddleware 메서드를 사용하면 됩니다. 일반적으로 이 메서드들은 애플리케이션의 AppServiceProvider에 있는 boot 메서드 안에서 호출합니다:

use Illuminate\Support\Facades\Http;

Http::globalRequestMiddleware(fn ($request) => $request->withHeader(
    'User-Agent', 'Example Application/1.0'
));

Http::globalResponseMiddleware(fn ($response) => $response->withHeader(
    'X-Finished-At', now()->toDateTimeString()
));

Guzzle 옵션

withOptions 메서드를 사용하면 나가는 요청에 추가적인 Guzzle 요청 옵션을 지정할 수 있습니다. withOptions 메서드는 key/value 쌍의 배열을 인자로 받습니다:

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

전역 옵션

모든 나가는 요청에 적용할 기본 옵션을 설정하고 싶다면 globalOptions 메서드를 사용하면 됩니다. 일반적으로 이 메서드는 애플리케이션의 AppServiceProvider에 있는 boot 메서드 안에서 호출합니다:

use Illuminate\Support\Facades\Http;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Http::globalOptions([
        'allow_redirects' => false,
    ]);
}

동시 요청(Concurrent Requests)

때로는 여러 HTTP 요청을 동시에 보내고 싶을 수 있습니다. 즉, 요청을 순차적으로 하나씩 처리하는 대신 여러 요청을 한꺼번에 디스패치하는 것입니다. 느린 응답 속도를 가진 외부 API와 통신할 때 이 방식을 사용하면 성능을 크게 향상시킬 수 있습니다.

요청 풀링(Request Pooling)

pool 메서드를 사용하면 이러한 동시 요청을 손쉽게 구현할 수 있습니다. pool 메서드는 Illuminate\Http\Client\Pool 인스턴스를 인자로 받는 클로저를 인수로 받으며, 이 클로저 안에서 요청 풀에 원하는 요청들을 추가할 수 있습니다:

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

$responses = Http::pool(fn (Pool $pool) => [
    $pool->get('http://localhost/first'),
    $pool->get('http://localhost/second'),
    $pool->get('http://localhost/third'),
]);

return $responses[0]->ok() &&
       $responses[1]->ok() &&
       $responses[2]->ok();

보시다시피 각 응답 인스턴스는 풀에 추가된 순서대로 배열 인덱스를 통해 접근할 수 있습니다. 순서 대신 이름으로 응답을 구분하고 싶다면 as 메서드를 사용해 요청에 이름을 지정할 수 있으며, 이렇게 하면 해당 이름으로 응답에 접근할 수 있습니다:

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

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

return $responses['first']->ok();

요청 풀의 최대 동시 처리 개수는 pool 메서드에 concurrency 인자를 전달해 제어할 수 있습니다. 이 값은 요청 풀을 처리하는 동안 동시에 전송될 수 있는 HTTP 요청의 최대 개수를 의미합니다:

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

풀에 포함된 요청 중 일부가 연결 단계에서 실패하면(예: 타임아웃이나 DNS 조회 실패), 해당 요청에 대응하는 $responses 배열의 항목은 Response 인스턴스가 아니라 Illuminate\Http\Client\ConnectionException 인스턴스가 됩니다:

foreach ($responses as $response) {
    if ($response instanceof Throwable) {
        // 요청이 연결에 실패한 경우...
    } elseif ($response->failed()) {
        // 연결은 되었지만 에러 응답을 받은 경우...
    }
}

동시 요청 커스터마이징하기

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

요청 배치 처리(Request Batching)

라라벨에서 동시 요청을 다루는 또 다른 방법은 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) {
    // 배치는 생성됐지만 아직 요청이 초기화되지 않은 상태...
})->progress(function (Batch $batch, int|string $key, Response $response) {
    // 개별 요청이 성공적으로 완료된 경우...
})->then(function (Batch $batch, array $results) {
    // 모든 요청이 성공적으로 완료된 경우...
})->catch(function (Batch $batch, int|string $key, Response|RequestException|ConnectionException $response) {
    // 배치 요청 중 실패가 감지된 경우...
})->finally(function (Batch $batch, array $results) {
    // 배치 실행이 모두 끝난 경우...
})->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 메서드를 호출해 배치가 시작된 이후에는 새로운 요청을 추가할 수 없습니다. 이를 시도하면 Illuminate\Http\Client\BatchInProgressException 예외가 발생합니다.

NOTE

pool은 단순히 여러 요청을 동시에 보내고 결과를 한 번에 받는 용도라면, batch는 여기에 더해 요청 진행 상황을 추적하거나 성공/실패에 따라 각각 다른 후속 처리를 하고 싶을 때 적합합니다. 큐의 Job 배치 처리와 개념이 비슷하다고 생각하면 이해하기 쉽습니다.

요청 배치의 최대 동시 처리 개수는 concurrency 메서드로 제어할 수 있습니다. 이 값은 배치를 처리하는 동안 동시에 전송될 수 있는 HTTP 요청의 최대 개수를 의미합니다:

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

배치 상태 확인하기

배치 완료 콜백에 전달되는 Illuminate\Http\Client\Batch 인스턴스는 배치에 포함된 요청들의 상태를 확인할 수 있는 다양한 프로퍼티와 메서드를 제공합니다:

// 배치에 할당된 요청의 총 개수...
$batch->totalRequests;

// 아직 처리되지 않은 요청의 개수...
$batch->pendingRequests;

// 실패한 요청의 개수...
$batch->failedRequests;

// 지금까지 처리가 완료된 요청의 개수...
$batch->processedRequests();

// 배치 실행이 모두 끝났는지 여부...
$batch->finished();

// 배치 내에 실패한 요청이 있는지 여부...
$batch->hasFailures();

배치 지연 실행하기(Deferring Batches)

defer 메서드를 호출하면 배치의 요청들이 즉시 실행되지 않습니다. 대신 라라벨은 현재 애플리케이션 요청에 대한 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) {
    // 모든 요청이 성공적으로 완료된 경우...
})->defer();

NOTE

배치 지연 실행은 "응답 이후 처리할 로그 전송, 알림 발송, 통계 집계" 같은 작업에 특히 유용합니다. 사용자는 응답을 기다릴 필요 없이 빠르게 결과를 받아볼 수 있고, 후속 HTTP 요청들은 백그라운드에서 처리됩니다.

매크로

Laravel HTTP 클라이언트는 "매크로"라는 기능을 제공합니다. 애플리케이션 전반에서 특정 서비스와 통신할 때 자주 사용하는 요청 경로나 헤더 설정을 간결하고 표현력 있는 방식으로 재사용할 수 있는 기능입니다. 매번 baseUrl과 헤더를 반복해서 작성하는 대신, 한 번 정의해두고 어디서든 호출해서 쓸 수 있다고 생각하면 됩니다.

매크로는 App\Providers\AppServiceProvider 클래스의 boot 메서드에서 정의합니다:

use Illuminate\Support\Facades\Http;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    Http::macro('github', function () {
        return Http::withHeaders([
            'X-Example' => 'example',
        ])->baseUrl('https://github.com');
    });
}

매크로를 설정하고 나면, 애플리케이션 어디에서든 해당 매크로를 호출해 지정된 설정이 적용된 펜딩 요청을 생성할 수 있습니다:

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

예를 들어 사내에서 사용하는 사내 결제 API나 알림 발송 API처럼 여러 컨트롤러·Job에서 반복적으로 호출하는 외부 서비스가 있다면, 이렇게 매크로로 등록해두면 매번 인증 헤더나 기본 URL을 설정할 필요 없이 간편하게 재사용할 수 있습니다.

테스트하기

라라벨의 다른 서비스들이 그렇듯, HTTP 클라이언트 역시 테스트를 쉽고 명확하게 작성할 수 있도록 다양한 기능을 제공합니다. Http 파사드의 fake 메서드를 사용하면 실제 요청을 보내는 대신 미리 정해둔 더미 응답을 반환하도록 HTTP 클라이언트에 지시할 수 있습니다.

응답 가짜(Fake)로 만들기

예를 들어 모든 요청에 대해 빈 본문에 200 상태 코드를 반환하도록 하려면, 인자 없이 fake 메서드를 호출하면 됩니다:

use Illuminate\Support\Facades\Http;

Http::fake();

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

특정 URL만 가짜 응답으로 처리하기

fake 메서드에 배열을 전달할 수도 있습니다. 이 배열의 키는 가짜 응답으로 처리하고 싶은 URL 패턴이고, 값은 해당 URL에 대응되는 응답입니다. URL 패턴에는 와일드카드 문자 *를 사용할 수 있습니다. 응답은 Http 파사드의 response 메서드로 직접 만들어 지정합니다:

Http::fake([
    // GitHub 엔드포인트에 대해 JSON 응답을 스텁(stub) 처리합니다...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, $headers),

    // Google 엔드포인트에 대해 문자열 응답을 스텁 처리합니다...
    'google.com/*' => Http::response('Hello World', 200, $headers),
]);

가짜 응답으로 등록되지 않은 URL로 요청을 보내면 실제로 요청이 실행됩니다. 패턴에 매칭되지 않는 모든 URL에 대한 기본(fallback) 응답을 지정하고 싶다면, 패턴으로 * 하나만 사용하면 됩니다:

Http::fake([
    // GitHub 엔드포인트에 대해 JSON 응답을 스텁 처리합니다...
    'github.com/*' => Http::response(['foo' => 'bar'], 200, ['Headers']),

    // 그 외 모든 엔드포인트에 대해 문자열 응답을 스텁 처리합니다...
    '*' => Http::response('Hello World', 200, ['Headers']),
]);

편의를 위해, 단순한 문자열·JSON·빈 응답이라면 응답 값 자리에 문자열, 배열, 정수를 바로 넘겨서 생성할 수도 있습니다:

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

예외 상황 가짜로 만들기

요청 도중 Illuminate\Http\Client\ConnectionException이 발생했을 때 애플리케이션이 올바르게 동작하는지 테스트해야 할 때가 있습니다. 이럴 땐 failedConnection 메서드를 사용해서 연결 예외가 발생한 것처럼 만들 수 있습니다:

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([
    // GitHub 엔드포인트에 대해 순차적인 응답 목록을 스텁 처리합니다...
    'github.com/*' => Http::sequence()
        ->push('Hello World', 200)
        ->push(['foo' => 'bar'], 200)
        ->pushStatus(404),
]);

시퀀스에 등록된 응답을 모두 소진한 뒤에 또 요청이 들어오면 예외가 발생합니다. 시퀀스가 비었을 때 반환할 기본 응답을 지정하고 싶다면 whenEmpty 메서드를 사용하세요:

Http::fake([
    // GitHub 엔드포인트에 대해 순차적인 응답 목록을 스텁 처리합니다...
    'github.com/*' => Http::sequence()
        ->push('Hello World', 200)
        ->push(['foo' => 'bar'], 200)
        ->whenEmpty(Http::response()),
]);

특정 URL 패턴을 지정하지 않고 응답 시퀀스만 가짜로 만들고 싶다면 Http::fakeSequence 메서드를 사용할 수 있습니다:

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

콜백을 이용한 Fake 처리

엔드포인트별로 더 복잡한 로직에 따라 응답을 결정해야 한다면, 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 인스턴스를 받아 불리언 값을 반환하는 클로저를 인자로 받습니다. 이 클로저가 지정한 조건에 맞는 요청이 하나라도 전송되었다면 테스트는 통과합니다:

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 메서드를 사용하면 지금까지 전송된 모든 요청과 그에 대응되는 응답을 한꺼번에 가져올 수 있습니다. 이 메서드는 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 메서드를 사용하세요. 이 메서드를 호출한 이후에는, 대응하는 가짜 응답이 지정되지 않은 요청은 실제로 전송되는 대신 예외를 던지게 됩니다:

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

NOTE

테스트 실행 중에 실수로 외부 API에 실제 요청을 보내는 사고를 막아주는 안전장치라고 생각하면 됩니다. 가짜 응답을 깜빡 등록하지 않았을 때 바로 눈치챌 수 있어 유용합니다.

대부분의 요청은 막되, 특정 요청만 예외적으로 허용하고 싶을 때도 있습니다. 이럴 때는 allowStrayRequests 메서드에 허용할 URL 패턴 배열을 전달하면 됩니다. 지정된 패턴과 일치하는 요청은 허용되고, 나머지 요청은 계속 예외를 던집니다:

use Illuminate\Support\Facades\Http;

Http::preventStrayRequests();

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

// 이 요청은 실제로 실행됩니다...
Http::get('http://127.0.0.1:5000/generate');

// 예외가 발생합니다...
Http::get('https://laravel.com');

이벤트

Laravel은 HTTP 요청을 전송하는 과정에서 세 가지 이벤트를 발생시킵니다. RequestSending 이벤트는 요청이 전송되기 직전에 발생하며, ResponseReceived 이벤트는 요청에 대한 응답을 받은 후에 발생합니다. 만약 요청에 대한 응답을 전혀 받지 못한 경우에는 ConnectionFailed 이벤트가 발생합니다.

RequestSending과 ConnectionFailed 이벤트는 모두 Illuminate\Http\Client\Request 인스턴스를 확인할 수 있는 $request라는 public 속성을 가지고 있습니다. 마찬가지로 ResponseReceived 이벤트는 $request 속성과 함께, Illuminate\Http\Client\Response 인스턴스를 확인할 수 있는 $response 속성을 가지고 있습니다. 애플리케이션 내에서 이러한 이벤트들을 위한 이벤트 리스너를 다음과 같이 작성할 수 있습니다:

use Illuminate\Http\Client\Events\RequestSending;

class LogRequest
{
    /**
     * 이벤트를 처리합니다.
     */
    public function handle(RequestSending $event): void
    {
        // $event->request ...
    }
}

NOTE

이러한 이벤트는 요청을 가로채서 로깅하거나 디버깅 목적으로 활용하기에 유용합니다. 다만 요청/응답 자체를 변형하는 작업이 필요하다면, 이 문서의 앞부분에서 다룬 미들웨어 기능을 사용하는 것이 더 적합합니다.

HTTP 클라이언트

소개

요청 보내기

URI 템플릿

요청 덤프하기

요청 데이터

GET 요청의 쿼리 파라미터

Form URL Encoded 요청 보내기

Raw 요청 본문 보내기

Multi-Part 요청 보내기

헤더

인증

Bearer 토큰

타임아웃

재시도

에러 처리

예외 발생시키기

Guzzle 미들웨어

전역 미들웨어

Guzzle 옵션

전역 옵션

HTTP 클라이언트

목차

소개

HTTP 클라이언트

요청 보내기

URI 템플릿

요청 내용 덤프하기

요청 데이터

GET 요청의 쿼리 파라미터

Form URL Encoded 요청 보내기

Raw 요청 바디 보내기

멀티파트 요청

헤더

인증

Bearer 토큰

타임아웃

재시도

에러 처리

예외 던지기

Guzzle 미들웨어

전역 미들웨어

Guzzle 옵션

전역 옵션

동시 요청(Concurrent Requests)

요청 풀링(Request Pooling)

동시 요청 커스터마이징하기

요청 배치 처리(Request Batching)

배치 상태 확인하기

배치 지연 실행하기(Deferring Batches)

매크로

테스트하기

응답 가짜(Fake)로 만들기

특정 URL만 가짜 응답으로 처리하기

예외 상황 가짜로 만들기

응답 시퀀스 가짜로 만들기

콜백을 이용한 Fake 처리

전송된 요청 검사하기

요청과 응답 기록 확인하기

의도하지 않은 실제 요청 막기

이벤트