HTTP 요청

번역일: 2026년 6월 25일

HTTP 요청

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

소개

Laravel의 Illuminate\Http\Request 클래스는 현재 처리 중인 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 = $request->url();

$urlWithQueryString = $request->fullUrl();

현재 URL에 쿼리 스트링 파라미터를 추가하고 싶다면 fullUrlWithQuery 메서드를 사용합니다. 이 메서드는 기존 쿼리 스트링에 주어진 배열을 병합합니다.

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

특정 쿼리 스트링 파라미터를 제외한 URL을 얻으려면 fullUrlWithoutQuery 메서드를 사용합니다.

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

요청 호스트 가져오기

host, httpHost, schemeAndHttpHost 메서드로 요청의 호스트 정보를 가져올 수 있습니다.

$request->host();           // 예: example.com
$request->httpHost();       // 예: example.com:8080
$request->schemeAndHttpHost(); // 예: https://example.com

HTTP 메서드 가져오기

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

JSON 응답을 기대하는 요청인지 빠르게 확인할 때는 expectsJson 메서드가 편리합니다.

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 메서드 종류에 관계없이 입력값을 가져옵니다.

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

두 번째 인수로 기본값을 지정할 수 있습니다. 해당 키의 값이 없으면 기본값이 반환됩니다.

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

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

$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 데이터에 접근할 수 있습니다. 중첩된 JSON 구조도 점 표기법으로 접근 가능합니다.

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

Stringable 입력값 가져오기

입력값을 단순 문자열 대신 Illuminate\Support\Stringable 인스턴스로 받고 싶다면 string 메서드를 사용합니다. 이를 통해 문자열 체이닝 메서드를 바로 활용할 수 있습니다.

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

정수형 입력값 가져오기

integer 메서드는 입력값을 정수로 변환하여 반환합니다. 값이 없거나 변환에 실패하면 지정한 기본값을 반환합니다. 페이지네이션 등 숫자 입력을 처리할 때 유용합니다.

$perPage = $request->integer('per_page');

불리언 입력값 가져오기

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

입력값이 배열인 경우 enums 메서드로 Enum 인스턴스 배열을 가져올 수 있습니다.

use App\Enums\Product;

$products = $request->enums('products', Product::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')) {
    // ...
}

isNotFilled 메서드는 값이 없거나 빈 문자열인지 확인합니다. 배열을 전달하면 모든 값이 비어 있을 때 true를 반환합니다.

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

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

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 () {
    // "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');

Blade 템플릿에서 폼을 다시 채울 때는 전역 old 헬퍼 함수를 사용하는 것이 더 편리합니다. 해당 필드의 이전 입력값이 없으면 null을 반환합니다.

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

쿠키

요청에서 쿠키 가져오기

Laravel이 생성하는 모든 쿠키는 암호화되고 인증 코드로 서명됩니다. 클라이언트에서 쿠키가 변조된 경우 무효로 처리됩니다. 요청에서 쿠키 값을 가져오려면 cookie 메서드를 사용합니다.

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

입력값 트리밍 및 정규화

Laravel은 기본적으로 Illuminate\Foundation\Http\Middleware\TrimStrings와 Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull 미들웨어를 전역 미들웨어 스택에 포함합니다. 이 미들웨어들은 요청의 모든 문자열 필드를 자동으로 트리밍하고, 빈 문자열을 null로 변환합니다. 덕분에 컨트롤러나 라우트에서 이런 정규화 처리를 별도로 신경 쓰지 않아도 됩니다.

입력값 정규화 비활성화

모든 요청에 대해 이 동작을 비활성화하려면 bootstrap/app.php 파일에서 $middleware->remove 메서드를 호출해 두 미들웨어를 제거합니다.

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

->withMiddleware(function (Middleware $middleware) {
    $middleware->remove([
        ConvertEmptyStringsToNull::class,
        TrimStrings::class,
    ]);
})

특정 요청에 대해서만 비활성화하려면 bootstrap/app.php에서 trimStrings와 convertEmptyStringsToNull 메서드를 사용합니다. 각 메서드는 클로저 배열을 받으며, 클로저가 true를 반환하는 요청에서는 정규화가 건너뛰어집니다.

->withMiddleware(function (Middleware $middleware) {
    $middleware->convert