HTTP 요청

번역일: 2026년 7월 2일

HTTP 요청

소개
요청 다루기
입력값
파일
- 업로드된 파일 조회
- 업로드된 파일 저장
신뢰할 수 있는 프록시 설정
신뢰할 수 있는 호스트 설정

소개

Laravel의 Illuminate\Http\Request 클래스는 현재 처리 중인 HTTP 요청을 객체 지향 방식으로 다룰 수 있게 해줍니다. 요청과 함께 전송된 입력값, 쿠키, 파일 등을 손쉽게 조회할 수 있습니다.

요청 다루기

요청 인스턴스 접근

현재 HTTP 요청 인스턴스를 얻으려면 라우트 클로저나 컨트롤러 메서드의 파라미터에 Illuminate\Http\Request 타입힌트를 추가하면 됩니다. Laravel 서비스 컨테이너가 자동으로 요청 인스턴스를 주입해 줍니다.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * 새 사용자를 저장합니다.
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->input('name');

        // 사용자 저장...

        return redirect('/users');
    }
}

라우트 클로저에서도 동일하게 타입힌트를 사용할 수 있습니다.

use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    // ...
});

의존성 주입과 라우트 파라미터

컨트롤러 메서드가 라우트 파라미터도 함께 받아야 한다면, 다른 의존성 파라미터 뒤에 라우트 파라미터를 나열하면 됩니다. 예를 들어 라우트가 다음과 같이 정의되어 있다면:

use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);

컨트롤러 메서드를 아래와 같이 작성하면 Request를 주입받으면서 id 라우트 파라미터에도 접근할 수 있습니다.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * 지정된 사용자를 수정합니다.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // 사용자 수정...

        return redirect('/users');
    }
}

요청 경로, 호스트, 메서드

Illuminate\Http\Request 인스턴스는 Symfony\Component\HttpFoundation\Request를 상속하며, 들어오는 HTTP 요청을 검사하는 다양한 메서드를 제공합니다.

요청 경로 조회

path 메서드는 요청의 경로 정보를 반환합니다. 예를 들어 요청 URL이 http://example.com/foo/bar라면 foo/bar를 반환합니다.

$uri = $request->path();

요청 경로 / 라우트 확인

is 메서드를 사용하면 요청 경로가 특정 패턴과 일치하는지 확인할 수 있습니다. * 문자를 와일드카드로 사용할 수 있습니다.

if ($request->is('admin/*')) {
    // ...
}

routeIs 메서드를 사용하면 요청이 이름 있는 라우트와 매칭되는지 확인할 수 있습니다.

if ($request->routeIs('admin.*')) {
    // ...
}

요청 URL 조회

전체 URL을 조회하려면 url 또는 fullUrl 메서드를 사용하세요. url은 쿼리 문자열을 제외한 URL을 반환하고, fullUrl은 쿼리 문자열을 포함해 반환합니다.

$url = $request->url();

$urlWithQueryString = $request->fullUrl();

현재 URL에 쿼리 파라미터를 추가하려면 fullUrlWithQuery 메서드를 사용합니다. 전달한 배열이 기존 쿼리 문자열과 병합됩니다.

$request->fullUrlWithQuery(['type' => 'phone']);

반대로 특정 쿼리 파라미터를 제외한 URL이 필요하다면 fullUrlWithoutQuery 메서드를 사용합니다.

$request->fullUrlWithoutQuery(['type']);

요청 호스트 조회

요청의 호스트 정보는 host, httpHost, schemeAndHttpHost 메서드로 조회할 수 있습니다.

$request->host();
$request->httpHost();
$request->schemeAndHttpHost();

요청 메서드 조회

method 메서드는 요청의 HTTP 메서드(동사)를 반환합니다. isMethod 메서드로 특정 HTTP 메서드인지 확인할 수도 있습니다.

$method = $request->method();

if ($request->isMethod('post')) {
    // ...
}

요청 헤더

header 메서드로 요청 헤더 값을 조회할 수 있습니다. 해당 헤더가 없으면 null을 반환하며, 두 번째 인수로 기본값을 지정할 수 있습니다.

$value = $request->header('X-Header-Name');

$value = $request->header('X-Header-Name', 'default');

hasHeader 메서드로 특정 헤더의 존재 여부를 확인할 수 있습니다.

if ($request->hasHeader('X-Header-Name')) {
    // ...
}

Authorization 헤더에서 Bearer 토큰을 간편하게 가져오려면 bearerToken 메서드를 사용하세요. 헤더가 없으면 빈 문자열을 반환합니다.

$token = $request->bearerToken();

요청 IP 주소

ip 메서드로 요청을 보낸 클라이언트의 IP 주소를 조회할 수 있습니다.

$ipAddress = $request->ip();

프록시를 통해 전달된 모든 클라이언트 IP 주소를 배열로 조회하려면 ips 메서드를 사용하세요. 원래 클라이언트 IP는 배열의 마지막에 위치합니다.

$ipAddresses = $request->ips();

NOTE

IP 주소는 클라이언트가 임의로 조작할 수 있으므로, 신뢰할 수 있는 정보로 다루기보다는 참고용으로만 활용하는 것이 좋습니다.

콘텐츠 협상

Laravel은 Accept 헤더를 통해 클라이언트가 원하는 콘텐츠 타입을 확인하는 여러 메서드를 제공합니다.

getAcceptableContentTypes 메서드는 요청이 허용하는 모든 콘텐츠 타입을 배열로 반환합니다.

$contentTypes = $request->getAcceptableContentTypes();

accepts 메서드는 주어진 콘텐츠 타입 배열 중 하나라도 허용되면 true를 반환합니다.

if ($request->accepts(['text/html', 'application/json'])) {
    // ...
}

prefers 메서드는 주어진 콘텐츠 타입 중 클라이언트가 가장 선호하는 타입을 반환합니다. 허용되는 타입이 없으면 null을 반환합니다.

$preferred = $request->prefers(['text/html', 'application/json']);

대부분의 애플리케이션은 HTML이나 JSON만 제공하므로, expectsJson 메서드를 사용하면 클라이언트가 JSON 응답을 기대하는지 빠르게 확인할 수 있습니다.

if ($request->expectsJson()) {
    // ...
}

PSR-7 요청

PSR-7 표준은 HTTP 메시지(요청/응답)에 대한 인터페이스를 정의합니다. Laravel 요청 대신 PSR-7 요청 인스턴스가 필요하다면 먼저 아래 라이브러리를 설치해야 합니다. Laravel은 내부적으로 Symfony HTTP Message Bridge 컴포넌트를 사용해 변환을 처리합니다.

composer require symfony/psr-http-message-bridgecomposer require nyholm/psr7

설치 후 라우트 클로저나 컨트롤러 메서드에 PSR-7 요청 인터페이스를 타입힌트로 지정하면 됩니다.

use Psr\Http\Message\ServerRequestInterface;

Route::get('/', function (ServerRequestInterface $request) {
    // ...
});

NOTE

라우트나 컨트롤러에서 PSR-7 응답 인스턴스를 반환하면, 프레임워크가 자동으로 Laravel 응답 인스턴스로 변환하여 처리합니다.

입력값

입력값 조회

전체 입력값 조회

all 메서드를 사용하면 모든 입력값을 배열로 가져올 수 있습니다. HTML 폼 요청이든 XHR 요청이든 동일하게 동작합니다.

$input = $request->all();

collect 메서드를 사용하면 전체 입력값을 컬렉션으로 받을 수 있습니다.

$input = $request->collect();

특정 키만 컬렉션으로 받을 수도 있습니다.

$request->collect('users')->each(function (string $user) {
    // ...
});

단일 입력값 조회

input 메서드는 HTTP 메서드(GET, POST 등)에 관계없이 입력값을 조회합니다.

$name = $request->input('name');

두 번째 인수로 기본값을 지정하면, 해당 키가 없을 때 기본값이 반환됩니다.

$name = $request->input('name', '홍길동');

배열 형태의 입력값은 "점(dot) 표기법"으로 접근할 수 있습니다.

$name = $request->input('products.0.name');

$names = $request->input('products.*.name');

인수 없이 호출하면 모든 입력값을 연관 배열로 반환합니다.

$input = $request->input();

쿼리 문자열에서 입력값 조회

input은 요청 본문과 쿼리 문자열 모두에서 값을 가져오지만, query는 쿼리 문자열에서만 값을 가져옵니다.

$name = $request->query('name');

$name = $request->query('name', '홍길동');

$query = $request->query();

JSON 입력값 조회

JSON 요청을 보낼 때 Content-Type 헤더가 application/json으로 설정되어 있으면, input 메서드로 JSON 데이터를 조회할 수 있습니다. 중첩된 구조에도 점 표기법을 사용할 수 있습니다.

$name = $request->input('user.name');

Stringable 입력값 조회

입력값을 단순 문자열이 아닌 Illuminate\Support\Stringable 인스턴스로 받으려면 string 메서드를 사용하세요. 메서드 체이닝으로 문자열 처리를 바로 이어갈 수 있습니다.

$name = $request->string('name')->trim();

Boolean 입력값 조회

HTML 체크박스처럼 "true", "on" 같은 문자열 형태의 불리언 값을 다룰 때는 boolean 메서드를 사용하세요. 1, "1", true, "true", "on", "yes"는 true로, 나머지는 false로 반환합니다.

$archived = $request->boolean('archived');

날짜 입력값 조회

날짜/시간 형식의 입력값은 date 메서드를 사용하면 Carbon 인스턴스로 바로 받을 수 있습니다. 해당 키가 없으면 null을 반환합니다.

$birthday = $request->date('birthday');

두 번째, 세 번째 인수로 날짜 포맷과 타임존을 지정할 수 있습니다.

$elapsed = $request->date('elapsed', '!H:i', 'Asia/Seoul');

입력값이 있지만 형식이 잘못된 경우 InvalidArgumentException이 발생합니다. date 메서드를 호출하기 전에 입력값 유효성 검사를 먼저 하는 것이 좋습니다.

Enum 입력값 조회

PHP Enum에 해당하는 입력값을 조회할 때는 enum 메서드를 사용하세요. 해당 키가 없거나 Enum에 일치하는 값이 없으면 null을 반환합니다.

use App\Enums\Status;

$status = $request->enum('status', Status::class);

동적 프로퍼티로 입력값 조회

Illuminate\Http\Request 인스턴스의 동적 프로퍼티로도 입력값에 접근할 수 있습니다. 예를 들어 폼에 name 필드가 있다면 다음과 같이 접근할 수 있습니다.

$name = $request->name;

동적 프로퍼티를 사용할 때 Laravel은 먼저 요청 페이로드에서 값을 찾고, 없으면 매칭된 라우트 파라미터에서 검색합니다.

일부 입력값만 조회

입력값의 일부만 가져오려면 only 또는 except 메서드를 사용하세요. 배열이나 가변 인수 형태 모두 지원합니다.

$input = $request->only(['username', 'password']);

$input = $request->only('username', 'password');

$input = $request->except(['credit_card']);

$input = $request->except('credit_card');

WARNING

only 메서드는 지정한 키 중 요청에 실제로 존재하는 값만 반환합니다. 요청에 없는 키는 결과에 포함되지 않습니다.

입력값 존재 확인

has 메서드로 특정 값이 요청에 포함되어 있는지 확인할 수 있습니다.

if ($request->has('name')) {
    // ...
}

배열을 전달하면 지정한 모든 키가 존재할 때만 true를 반환합니다.

if ($request->has(['name', 'email'])) {
    // ...
}

hasAny 메서드는 지정한 키 중 하나라도 존재하면 true를 반환합니다.

if ($request->hasAny(['name', 'email'])) {
    // ...
}

whenHas 메서드는 값이 존재할 때 클로저를 실행합니다. 두 번째 클로저는 값이 없을 때 실행됩니다.

$request->whenHas('name', function (string $input) {
    // "name" 값이 존재하는 경우...
}, function () {
    // "name" 값이 없는 경우...
});

값이 존재하면서 빈 문자열이 아닌지 확인하려면 filled 메서드를 사용하세요.

if ($request->filled('name')) {
    // ...
}

anyFilled는 지정한 값 중 하나라도 빈 문자열이 아니면 true를 반환합니다.

if ($request->anyFilled(['name', 'email'])) {
    // ...
}

whenFilled 메서드는 값이 존재하고 빈 문자열이 아닐 때 클로저를 실행합니다.

$request->whenFilled('name', function (string $input) {
    // "name" 값이 채워진 경우...
}, function () {
    // "name" 값이 비어 있는 경우...
});

특정 키가 요청에 없는지 확인하려면 missing과 whenMissing 메서드를 사용하세요.

if ($request->missing('name')) {
    // ...
}

$request->whenMissing('name', function (array $input) {
    // "name" 값이 없는 경우...
}, function () {
    // "name" 값이 있는 경우...
});

추가 입력값 병합

요청의 기존 입력값에 수동으로 값을 추가하거나 덮어쓰려면 merge 메서드를 사용하세요. 이미 존재하는 키는 전달한 값으로 덮어씁니다.

$request->merge(['votes' => 0]);

해당 키가 아직 없을 때만 병합하려면 mergeIfMissing 메서드를 사용하세요.

$request->mergeIfMissing(['votes' => 0]);

이전 입력값

Laravel은 한 요청의 입력값을 다음 요청에서도 사용할 수 있도록 세션에 보관하는 기능을 제공합니다. 유효성 검사 실패 후 폼을 다시 채울 때 주로 활용됩니다. 단, Laravel의 유효성 검사 기능을 사용한다면 이 세션 플래싱 메서드를 직접 호출할 필요 없이 자동으로 처리됩니다.

입력값을 세션에 플래시

flash 메서드는 현재 입력값을 세션에 저장해 다음 요청에서 사용할 수 있게 합니다.

$request->flash();

일부 입력값만 저장하거나, 비밀번호처럼 민감한 정보를 제외할 때는 flashOnly와 flashExcept 메서드를 사용하세요.

$request->flashOnly(['username', 'email']);

$request->flashExcept('password');

입력값 플래시 후 리다이렉트

입력값을 세션에 저장한 뒤 이전 페이지로 리다이렉트하는 패턴은 매우 자주 사용됩니다. withInput 메서드를 리다이렉트에 체이닝하면 두 동작을 한 번에 처리할 수 있습니다.

return redirect('form')->withInput();

return redirect()->route('user.create')->withInput();

return redirect('form')->withInput(
    $request->except('password')
);

이전 입력값 조회

이전 요청에서 플래시된 입력값을 가져오려면 old 메서드를 사용하세요.

$username = $request->old('username');

전역 헬퍼 함수 old()를 사용하면 더 간편합니다. 특히 Blade 템플릿에서 폼을 다시 채울 때 유용합니다. 이전 입력값이 없으면 null을 반환합니다.

<input type="text" name="username" value="{{ old('username') }}">

쿠키

요청에서 쿠키 조회

Laravel이 생성하는 모든 쿠키는 암호화되고 인증 코드로 서명되어 있습니다. 클라이언트가 쿠키를 변조하면 유효하지 않은 것으로 처리됩니다. 쿠키 값을 조회하려면 cookie 메서드를 사용하세요.

$value = $request->cookie('name');

입력값 트리밍 및 정규화

Laravel은 기본적으로 App\Http\Middleware\TrimStrings와 Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull 미들웨어를 전역 미들웨어 스택에 포함합니다. 이 미들웨어들은 들어오는 모든 문자열 필드의 앞뒤 공백을 자동으로 제거하고, 빈 문자열 필드를 null로 변환합니다. 덕분에 라우트나 컨트롤러에서 이러한 정규화를 별도로 처리할 필요가 없습니다.

입력값 정규화 비활성화

모든 요청에 대해 이 동작을 비활성화하려면 App\Http\Kernel 클래스의 $middleware 속성에서 해당 미들웨어를 제거하면 됩니다.

특정 요청에만 비활성화하고 싶다면 두 미들웨어가 제공하는 skipWhen 메서드를 활용하세요. 클로저가 true를 반환하면 해당 요청에서는 정규화가 건너뜁니다. 일반적으로 AppServiceProvider의 boot 메서드에서 호출합니다.

use App\Http\Middleware\TrimStrings;
use Illuminate\Http\Request;
use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;

/**
 * 애플리케이션 서비스를 부트스트랩합니다.
 */
public function boot(): void
{
    TrimStrings::skipWhen(function (Request $request) {
        return $request->is('admin/*');
    });

    ConvertEmptyStringsToNull::skipWhen(function (Request $request) {
        // ...
    });
}

파일

업로드된 파일 조회

file 메서드 또는 동적 프로퍼티를 사용해 업로드된 파일을 조회할 수 있습니다. file 메서드는 PHP SplFileInfo를 상속한 Illuminate\Http\UploadedFile 인스턴스를 반환합니다.

$file = $request->file('photo');

$file = $request->photo;

hasFile 메서드로 파일이 요청에 포함되어 있는지 확인할 수 있습니다.

if ($request->hasFile('photo')) {
    // ...
}

업로드 성공 검증

파일이 존재하는지 확인하는 것 외에, isValid 메서드로 업로드 과정에서 문제가 없었는지 검증할 수 있습니다.

if ($request->file('photo')->isValid()) {
    // ...
}

파일 경로 및 확장자

UploadedFile 클래스는 파일의 전체 경로와 확장자를 조회하는 메서드도 제공합니다. extension 메서드는 파일 내용을 기반으로 확장자를 추측하므로, 클라이언트가 전송한 확장자와 다를 수 있습니다.

$path = $request->photo->path();

$extension = $request->photo->extension();

그 외 파일 메서드

UploadedFile 인스턴스에는 다양한 메서드가 있습니다. 자세한 내용은 클래스 API 문서를 참고하세요.

업로드된 파일 저장

업로드된 파일을 저장하려면 설정된 파일시스템 중 하나를 사용합니다. UploadedFile 클래스의 store 메서드는 파일을 로컬 파일시스템이나 Amazon S3 같은 클라우드 스토리지로 이동시킵니다.

store 메서드의 첫 번째 인수는 파일시스템 루트 디렉토리 기준의 저장 경로입니다. 파일명을 지정하지 않으면 고유한 ID가 자동으로 파일명으로 사용됩니다. 두 번째 인수는 사용할 디스크 이름이며, 메서드는 디스크 루트 기준 상대 경로를 반환합니다.

$path = $request->photo->store('images');

$path = $request->photo->store('images', 's3');

파일명을 직접 지정하려면 storeAs 메서드를 사용하세요.

$path = $request->photo->storeAs('images', 'filename.jpg');

$path = $request->photo->storeAs('images', 'filename.jpg', 's3');

NOTE

Laravel의 파일 저장에 대한 더 자세한 내용은 파일 스토리지 문서를 참고하세요.

신뢰할 수 있는 프록시 설정

로드 밸런서 뒤에서 TLS/SSL을 종료하는 환경에서는 url 헬퍼가 HTTPS 링크를 생성하지 못하는 경우가 있습니다. 로드 밸런서가 포트 80으로 트래픽을 전달할 때 애플리케이션이 보안 링크를 생성해야 한다는 사실을 인식하지 못하기 때문입니다.

이 문제는 App\Http\Middleware\TrustProxies 미들웨어로 해결할 수 있습니다. $proxies 속성에 신뢰할 로드 밸런서나 프록시의 IP 주소를 지정하고, $headers 속성에는 신뢰할 프록시 헤더를 설정합니다.

<?php

namespace App\Http\Middleware;

use Illuminate\Http\Middleware\TrustProxies as Middleware;
use Illuminate\Http\Request;

class TrustProxies extends Middleware
{
    /**
     * 신뢰할 프록시 목록
     *
     * @var string|array
     */
    protected $proxies = [
        '192.168.1.1',
        '192.168.1.2',
    ];

    /**
     * 프록시 감지에 사용할 헤더
     *
     * @var int
     */
    protected $headers = Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_HOST | Request::HEADER_X_FORWARDED_PORT | Request::HEADER_X_FORWARDED_PROTO;
}

NOTE

AWS Elastic Load Balancing을 사용하는 경우 $headers 값을 Request::HEADER_X_FORWARDED_AWS_ELB로 설정해야 합니다. $headers 속성에서 사용할 수 있는 상수에 대한 자세한 내용은 Symfony의 프록시 신뢰 설정 문서를 참고하세요.

모든 프록시 신뢰

Amazon AWS나 기타 클라우드 로드 밸런서 서비스를 사용할 때 실제 밸런서의 IP 주소를 알 수 없는 경우, *를 사용하여 모든 프록시를 신뢰할 수 있습니다.

/**
 * 신뢰할 프록시 목록
 *
 * @var string|array
 */
protected $proxies = '*';

신뢰할 수 있는 호스트 설정

기본적으로 Laravel은 HTTP 요청의 Host 헤더 값에 관계없이 모든 요청에 응답하며, 웹 요청 중 절대 URL을 생성할 때도 Host 헤더 값을 사용합니다.

일반적으로는 Nginx나 Apache 같은 웹 서버에서 특정 호스트명의 요청만 애플리케이션으로 전달하도록 설정합니다. 그러나 웹 서버를 직접 수정할 수 없는 상황이라면 App\Http\Middleware\TrustHosts 미들웨어를 활성화하여 Laravel이 특정 호스트명에만 응답하도록 제한할 수 있습니다.

TrustHosts 미들웨어는 이미 $middleware 스택에 포함되어 있으나 주석 처리되어 있습니다. 주석을 해제하여 활성화한 뒤, hosts 메서드에 허용할 호스트명을 지정하세요. 지정된 호스트 이외의 Host 헤더를 가진 요청은 거부됩니다.

/**
 * 신뢰할 호스트 패턴 목록
 *
 * @return array<int, string>
 */
public function hosts(): array
{
    return [
        'laravel.test',
        $this->allSubdomainsOfApplicationUrl(),
    ];
}

allSubdomainsOfApplicationUrl 헬퍼 메서드는 app.url 설정값의 모든 서브도메인을 허용하는 정규 표현식을 반환합니다. 와일드카드 서브도메인을 사용하는 애플리케이션을 구축할 때 편리하게 활용할 수 있습니다.