HTTP 요청

업데이트됨

번역일: 2026년 7월 15일

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

원문 수정: 2026년 7월 15일
번역 갱신: 2026년 7월 15일

HTTP 요청

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

소개

Laravel의 Illuminate\Http\Request 클래스는 현재 HTTP 요청을 객체 형태로 다룰 수 있게 해줍니다. 입력값, 쿠키, 업로드 파일 조회는 물론, 요청 경로나 메서드 확인까지 다양한 기능을 제공합니다.

요청 다루기

요청 객체 접근하기

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

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request): void
    {
        $name = $request->input('name');

        // ...
    }
}

라우트 파라미터와 함께 사용하기

컨트롤러 메서드에서 라우트 파라미터도 함께 받아야 한다면, Request 타입힌트 뒤에 라우트 파라미터를 선언하세요. 예를 들어 아래와 같이 라우트가 정의된 경우:

use App\Http\Controllers\UserController;

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

컨트롤러 메서드에서 Request를 첫 번째 파라미터로, $id를 두 번째 파라미터로 선언하면 됩니다.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    public function update(Request $request, string $id): void
    {
        // ...
    }
}

클로저 라우트에서 사용하기

컨트롤러뿐 아니라 클로저 형태의 라우트에서도 동일하게 타입힌트를 사용할 수 있습니다.

use Illuminate\Http\Request;

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

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

Illuminate\Http\Request 인스턴스는 HTTP 요청을 검사하기 위한 다양한 메서드를 제공합니다. 주요 메서드를 살펴보겠습니다.

요청 경로 가져오기

path 메서드는 요청 경로를 반환합니다. 예를 들어 https://example.com/user/profile로 요청이 들어왔다면 user/profile을 반환합니다.

$uri = $request->path();

경로 패턴 확인하기

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

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

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

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

전체 URL 가져오기

요청의 전체 URL을 가져오려면 url 또는 fullUrl 메서드를 사용하세요. url은 쿼리 스트링을 제외한 URL을, fullUrl은 쿼리 스트링을 포함한 URL을 반환합니다.

$url = $request->url();

$urlWithQueryString = $request->fullUrl();

현재 URL에 쿼리 스트링 데이터를 추가하고 싶다면 fullUrlWithQuery 메서드를 사용하세요. 이 메서드는 전달한 배열을 현재 쿼리 스트링과 병합합니다.

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

특정 쿼리 스트링 파라미터를 제외한 URL이 필요하다면 fullUrlWithoutQuery 메서드를 사용하세요.

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

호스트 정보 가져오기

요청의 호스트 정보를 가져오는 메서드는 세 가지입니다.

$request->host();       // 호스트명
$request->httpHost();   // 호스트명 + 포트 (필요 시)
$request->schemeAndHttpHost(); // 스킴(http/https) + 호스트명 + 포트

요청 메서드 확인하기

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

$method = $request->method();

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

요청 헤더

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

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

$value = $request->header('X-Header-Name', '기본값');

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

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

Bearer 토큰은 bearerToken 메서드로 간편하게 가져올 수 있습니다. Authorization 헤더가 없거나 Bearer 토큰이 아닌 경우 빈 문자열을 반환합니다.

$token = $request->bearerToken();

요청 IP 주소

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

$ipAddress = $request->ip();

프록시를 거쳐 전달된 IP 주소를 포함한 전체 목록이 필요하다면 ips 메서드를 사용하세요. 배열의 마지막 항목이 가장 최초의 클라이언트 IP입니다.

$ipAddresses = $request->ips();

NOTE

IP 주소는 기본적으로 신뢰할 수 없는 사용자 입력입니다. 신뢰할 수 있는 프록시를 통해 전달된 실제 클라이언트 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 메서드를 활용하세요. API 클라이언트를 구분할 때 자주 사용됩니다.

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

PSR-7 요청

PSR-7 표준은 HTTP 메시지(요청 및 응답)에 대한 인터페이스를 정의합니다. Laravel의 기본 요청 객체 대신 PSR-7 요청 객체를 사용하고 싶다면, 몇 가지 라이브러리를 설치해야 합니다. Laravel은 Symfony HTTP Message Bridge 컴포넌트를 사용해 Laravel 요청/응답을 PSR-7 호환 구현체로 변환합니다.

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이 자동으로 Laravel 응답 인스턴스로 변환하여 출력합니다.

HTTP 요청

소개

Laravel의 Illuminate\Http\Request 클래스는 현재 처리 중인 HTTP 요청과 객체 지향 방식으로 상호작용할 수 있게 해줍니다. 요청에 포함된 입력값, 쿠키, 파일 등을 손쉽게 가져올 수 있습니다.

요청과 상호작용하기

요청 인스턴스 접근

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

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request): void
    {
        $name = $request->input('name');

        // ...
    }
}

앞서 설명한 대로, 라우트 클로저에서도 동일하게 Illuminate\Http\Request 타입을 선언하면 자동으로 주입됩니다.

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\Request;

class UserController extends Controller
{
    public function update(Request $request, string $id): void
    {
        // ...
    }
}

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

Illuminate\Http\Request 인스턴스는 들어온 HTTP 요청을 검사하는 다양한 메서드를 제공하며, Symfony\Component\HttpFoundation\Request 클래스를 상속합니다. 자주 사용하는 메서드들을 아래에서 소개합니다.

요청 경로 가져오기

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

$uri = $request->path();

요청 경로 / 라우트 확인

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

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

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

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

요청 URL 가져오기

전체 요청 URL을 가져오려면 url 또는 fullUrl 메서드를 사용합니다. 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 또는 example.com:8080
$request->schemeAndHttpHost(); // https://example.com

요청 HTTP 메서드 가져오기

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

$method = $request->method();

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

요청 헤더

Illuminate\Http\Request 인스턴스의 header 메서드로 요청 헤더를 가져올 수 있습니다. 해당 헤더가 없으면 null을 반환하며, 두 번째 인자로 기본값을 지정할 수도 있습니다.

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

$value = $request->header('X-Header-Name', '기본값');

hasHeader 메서드로 특정 헤더가 존재하는지 확인할 수 있습니다.

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

편의를 위해 bearerToken 메서드를 사용하면 Authorization 헤더에서 Bearer 토큰을 바로 가져올 수 있습니다. 헤더가 없으면 빈 문자열을 반환합니다.

$token = $request->bearerToken();

요청 IP 주소

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

$ipAddress = $request->ip();

로드 밸런서나 프록시를 거쳐 전달된 IP 주소 목록(원본 클라이언트 IP 포함)이 필요하다면 ips 메서드를 사용하세요. 가장 마지막 IP가 최종 클라이언트 IP입니다.

$ipAddresses = $request->ips();

NOTE

IP 주소는 기본적으로 신뢰할 수 없는 사용자 입력입니다. 실제 클라이언트 IP가 중요한 경우 신뢰할 수 있는 프록시 설정(TrustProxies 미들웨어)을 먼저 구성하세요.

콘텐츠 협상

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 컴포넌트를 이용해 일반적인 Laravel 요청과 응답을 PSR-7 호환 구현체로 변환합니다.

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

collect 메서드에 키를 지정하면 해당 입력값의 일부만 컬렉션으로 가져올 수도 있습니다.

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

특정 입력값 가져오기

input 메서드를 사용하면 HTTP 메서드에 관계없이 특정 입력값을 가져올 수 있습니다.

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

두 번째 인자로 기본값을 지정할 수 있으며, 해당 입력값이 없을 때 반환됩니다.

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

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

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

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

인자 없이 input 메서드를 호출하면 모든 입력값을 연관 배열로 가져옵니다.

$input = $request->input();

쿼리 스트링에서 입력값 가져오기

input 메서드는 쿼리 스트링을 포함한 전체 요청 페이로드에서 값을 가져오지만, query 메서드는 쿼리 스트링에서만 값을 가져옵니다.

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

해당 쿼리 스트링 파라미터가 없을 때 반환할 기본값을 지정할 수 있습니다.

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

인자 없이 query 메서드를 호출하면 모든 쿼리 스트링 값을 연관 배열로 가져옵니다.

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

정수 입력값 가져오기

입력값을 정수로 가져오려면 integer 메서드를 사용하세요. 값이 없거나 변환에 실패하면 지정한 기본값을 반환합니다. 페이지네이션 처리 등에 유용합니다.

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

불리언 입력값 가져오기

체크박스처럼 "truthy" 문자열값(예: "true", "on", "1")을 다룰 때는 boolean 메서드를 사용하세요. 그 외의 값은 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);

입력값이 Enum 값의 배열인 경우 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');

NOTE

only 메서드는 지정한 키/값 쌍만 반환합니다. 요청에 없는 키는 결과에 포함되지 않습니다.

입력값 존재 여부 확인

has 메서드로 특정 값이 요청에 존재하는지 확인할 수 있습니다. 값이 존재하면 true를 반환합니다.

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

배열을 전달하면 지정된 값이 모두 존재하는지 확인합니다.

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

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

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

whenHas 메서드는 값이 존재하는 경우 지정한 클로저를 실행합니다.

$request->whenHas('name', function (string $input) {
    // ...
});

두 번째 클로저를 전달하면 값이 존재하지 않을 때 실행됩니다.

$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) {
    // ...
});

두 번째 클로저를 전달하면 값이 "filled"가 아닐 때 실행됩니다.

$request->whenFilled('name', function (string $input) {
    // 'name' 값이 채워져 있을 때
}, function () {
    // 'name' 값이 비어있을 때
});

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

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

$request->whenMissing('name', function () {
    // 'name' 값이 없을 때
}, function () {
    // 'name' 값이 있을 때
});

추가 입력값 병합

기존 요청 입력 데이터에 값을 직접 추가하거나 기본값을 설정해야 할 때는 merge 또는 mergeIfMissing 메서드를 사용하세요.

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

mergeIfMissing 메서드는 해당 키가 요청에 아직 없을 때만 값을 병합합니다.

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

이전 입력값 (Old Input)

Laravel은 한 요청에서 입력한 값을 다음 요청에서 유지할 수 있게 해줍니다. 유효성 검사 오류 발생 후 폼을 다시 표시할 때 특히 유용합니다. 단, Laravel의 유효성 검사 기능을 사용하면 이 플래시 기능이 자동으로 처리되므로 직접 호출할 필요가 없는 경우가 많습니다.

입력값을 세션에 플래시하기

Illuminate\Http\Request 클래스의 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')
);

이전 입력값 가져오기

이전 요청에서 플래시된 입력값을 가져오려면 Illuminate\Http\Request 인스턴스의 old 메서드를 사용하세요. 세션에서 이전에 플래시된 입력값을 꺼내옵니다.

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

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

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

쿠키

요청에서 쿠키 가져오기

Laravel이 생성한 모든 쿠키는 인증 코드로 암호화되고 서명됩니다. 클라이언트가 쿠키를 변조하면 유효하지 않은 것으로 간주됩니다. 요청에서 쿠키 값을 가져오려면 Illuminate\Http\Request 인스턴스의 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->convertEmptyStringsToNull(except: [
        fn (Request $request) => $request->is('api/*'),
    ]);

    $middleware->trimStrings(except: [
        fn (Request $request) => $request->is('api/*'),
    ]);
})

파일

업로드된 파일 가져오기

Illuminate\Http\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 클래스의 store 메서드는 업로드된 파일을 로컬 파일시스템이나 AWS 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번 포트로 트래픽이 전달되어 애플리케이션이 보안 링크를 생성해야 한다는 것을 알지 못하기 때문입니다.

이런 문제를 해결하려면 Laravel에 내장된 Illuminate\Http\Middleware\TrustProxies 미들웨어를 사용하면 됩니다. 이 미들웨어를 통해 애플리케이션이 신뢰해야 할 로드 밸런서나 프록시를 빠르게 설정할 수 있습니다. 신뢰할 수 있는 프록시는 애플리케이션의 bootstrap/app.php 파일에서 trustProxies 미들웨어 메서드로 지정합니다.

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: [
        '192.168.1.1',
        '10.0.0.0/8',
    ]);
})

신뢰할 수 있는 프록시 설정 외에도, 신뢰해야 할 프록시 헤더도 설정할 수 있습니다.

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: [
        '192.168.1.1',
        '10.0.0.0/8',
    ], headers: Request::HEADER_X_FORWARDED_FOR |
        Request::HEADER_X_FORWARDED_HOST |
        Request::HEADER_X_FORWARDED_PORT |
        Request::HEADER_X_FORWARDED_PROTO |
        Request::HEADER_X_FORWARDED_AWS_ELB
    );
})

NOTE

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

모든 프록시 신뢰하기

AWS나 다른 클라우드 로드 밸런서 공급자를 사용하는 경우, 실제 밸런서의 IP 주소를 알 수 없을 수 있습니다. 이 경우 *를 사용해 모든 프록시를 신뢰하도록 설정할 수 있습니다.

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: '*');
})

WARNING

모든 프록시를 신뢰하도록 설정하면 보안상 위험할 수 있습니다. 악의적인 사용자가 요청 헤더를 조작할 수 있으므로, 신뢰할 수 있는 IP 범위를 명시적으로 지정하는 것을 권장합니다.

신뢰할 수 있는 호스트 설정

기본적으로 Laravel은 HTTP 요청의 Host 헤더 값에 관계없이 모든 요청에 응답합니다. 또한 웹 요청 중 애플리케이션의 절대 URL을 생성할 때 Host 헤더의 값이 사용됩니다.

일반적으로 Nginx나 Apache 같은 웹 서버에서 특정 호스트 이름과 일치하는 요청만 애플리케이션으로 전달하도록 설정해야 합니다. 하지만 웹 서버를 직접 설정하는 것이 어렵고 특정 호스트에서만 응답하도록 Laravel에 직접 설정하고 싶다면, bootstrap/app.php에서 trustHosts 미들웨어 메서드를 사용하면 됩니다.

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustHosts(at: ['laravel.test']);
})

기본적으로 애플리케이션의 APP_URL 설정에 포함된 서브도메인에서 오는 요청도 자동으로 신뢰됩니다. 이 동작을 비활성화하려면 subdomains 인자를 사용하세요.

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustHosts(at: ['laravel.test'], subdomains: false);
})

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

경로, 호스트, HTTP 메서드

Illuminate\Http\Request 인스턴스는 Symfony\Component\HttpFoundation\Request를 상속하며, 요청을 검사하는 다양한 메서드를 제공합니다. 가장 자주 사용하는 메서드들을 살펴보겠습니다.

요청 경로 가져오기

path 메서드는 요청의 경로 정보를 반환합니다. 예를 들어 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을 반환합니다.

$url = $request->url();

$urlWithQueryString = $request->fullUrl();

현재 URL에 쿼리 스트링을 추가하고 싶다면 fullUrlWithQuery 메서드를 사용하세요. 전달한 배열이 기존 쿼리 스트링과 병합됩니다.

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

특정 쿼리 스트링 파라미터를 제외한 URL이 필요하다면 fullUrlWithoutQuery 메서드를 사용하세요.

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

요청 호스트 가져오기

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

// 예: http://localhost:8000 으로 요청이 들어온 경우
$request->host();              // localhost
$request->httpHost();          // localhost:8000
$request->schemeAndHttpHost(); // http://localhost:8000

HTTP 메서드 가져오기

method 메서드는 요청의 HTTP 동사(verb)를 반환합니다. 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를, 그렇지 않으면 false를 반환합니다.

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

prefers 메서드는 전달한 콘텐츠 타입 배열 중 클라이언트가 가장 선호하는 타입을 반환합니다. 허용하는 타입이 없으면 null을 반환합니다.

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

많은 애플리케이션이 HTML이나 JSON만 응답하는 경우가 많으므로, expectsJson 메서드를 사용하면 요청이 JSON 응답을 기대하는지 빠르게 확인할 수 있습니다.

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

AI 에이전트나 Markdown을 소비하는 클라이언트를 지원해야 하는 경우, wantsMarkdown과 acceptsMarkdown 메서드로 Markdown 응답 여부를 확인할 수 있습니다.

if ($request->wantsMarkdown()) {
    // 클라이언트가 가장 선호하는 콘텐츠 타입이 text/markdown입니다...
}

if ($request->acceptsMarkdown()) {
    // 클라이언트가 Markdown 응답을 허용합니다...
}

PSR-7 요청

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

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

라이브러리를 설치한 후, 라우트 클로저나 컨트롤러 메서드에서 PSR-7 요청 인터페이스를 타입힌트하면 PSR-7 요청 인스턴스를 받을 수 있습니다.

use Psr\Http\Message\ServerRequestInterface;

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

NOTE

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

입력값 조회

전체 입력값 조회

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

$input = $request->all();

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

$input = $request->collect();

특정 키만 컬렉션으로 가져오는 것도 가능합니다.

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

단일 입력값 조회

Illuminate\Http\Request 인스턴스의 input 메서드를 사용하면 HTTP 메서드(GET, POST 등)와 무관하게 모든 입력값에 접근할 수 있습니다.

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

두 번째 인수로 기본값을 지정할 수 있습니다. 해당 키가 요청에 없을 경우 이 값이 반환됩니다.

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

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

$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 형태로 조회

string 메서드를 사용하면 입력값을 기본 string 타입 대신 Illuminate\Support\Stringable 인스턴스로 받을 수 있습니다. 문자열 조작 메서드를 체이닝하는 데 유용합니다.

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

정수형으로 조회

integer 메서드는 입력값을 정수로 변환해서 반환합니다. 값이 없거나 변환에 실패하면 지정한 기본값이 반환됩니다. 페이지네이션의 per_page 파라미터처럼 숫자 입력을 다룰 때 특히 유용합니다.

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

불리언 형태로 조회

HTML 체크박스처럼 "true", "on" 같은 문자열 형태의 truthy 값을 다룰 때는 boolean 메서드를 사용하면 편리합니다. 1, "1", true, "true", "on", "yes"는 true로 처리하며, 그 외의 값은 모두 false를 반환합니다.

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

배열 형태로 조회

array 메서드는 입력값을 항상 배열로 반환합니다. 해당 키의 값이 없으면 빈 배열이 반환됩니다.

$versions = $request->array('versions');

날짜/시간 값 조회

date 메서드를 사용하면 날짜·시간 입력값을 Carbon 인스턴스로 받을 수 있습니다. 해당 키가 없으면 null이 반환됩니다.

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

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

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

입력값이 있지만 포맷이 유효하지 않으면 InvalidArgumentException이 발생합니다. date 메서드를 호출하기 전에 반드시 입력값을 검증하는 것을 권장합니다.

시간 간격 값 조회

interval 메서드를 사용하면 시간 간격을 나타내는 입력값을 CarbonInterval 인스턴스로 받을 수 있습니다. 해당 키가 없으면 null이 반환됩니다.

$duration = $request->interval('duration');

입력값이 숫자인 경우 두 번째 인수로 단위를 지정할 수 있습니다. second, minute, day 같은 문자열이나 Carbon\Unit 열거형을 사용할 수 있습니다.

use Carbon\Unit;

$timeout = $request->interval('timeout', 'second');

$delay = $request->interval('delay', Unit::Minute);

입력값이 있지만 포맷이 유효하지 않으면 InvalidArgumentException이 발생합니다. interval 메서드 호출 전에 입력값을 검증하는 것을 권장합니다.

Enum 값 조회

PHP Enum에 해당하는 입력값은 enum 메서드로 조회할 수 있습니다. 해당 키가 없거나 Enum에 일치하는 값이 없으면 null이 반환됩니다. 첫 번째 인수로 키 이름, 두 번째 인수로 Enum 클래스를 지정합니다.

use App\Enums\Status;

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

세 번째 인수로 기본값을 지정할 수도 있습니다. 값이 없거나 유효하지 않은 경우 이 기본값이 반환됩니다.

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

입력값이 Enum 배열인 경우 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')) {
    // ...
}

배열을 전달하면 지정한 모든 키가 존재하는지 확인합니다.

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

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

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

whenHas 메서드는 값이 존재할 때 클로저를 실행합니다.

$request->whenHas('name', function (string $input) {
    // ...
});

두 번째 클로저를 전달하면 값이 존재하지 않을 때 실행됩니다.

$request->whenHas('name', function (string $input) {
    // "name" 값이 존재할 때
}, function () {
    // "name" 값이 없을 때
});

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

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

반대로 값이 없거나 빈 문자열인지 확인하려면 isNotFilled 메서드를 사용합니다.

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

배열을 전달하면 지정한 모든 값이 없거나 비어 있는지 확인합니다.

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

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

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

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

$request->whenFilled('name', function (string $input) {
    // ...
});

두 번째 클로저를 전달하면 값이 "filled" 상태가 아닐 때 실행됩니다.

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

이전 입력값 (Old Input)

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

Laravel은 전역 헬퍼 함수 old()도 제공합니다. Blade 템플릿에서 폼을 다시 채울 때는 이 헬퍼를 사용하는 것이 더 간편합니다. 해당 필드의 이전 값이 없으면 null이 반환됩니다.

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

쿠키

요청에서 쿠키 조회

Laravel 프레임워크가 생성하는 모든 쿠키는 암호화되고 인증 코드로 서명됩니다. 따라서 클라이언트가 값을 변조하면 해당 쿠키는 유효하지 않은 것으로 처리됩니다. 쿠키 값을 가져오려면 Illuminate\Http\Request 인스턴스의 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): void {
    $middleware->remove([
        ConvertEmptyStringsToNull::class,
        TrimStrings::class,
    ]);
})

특정 요청에 대해서만 선택적으로 비활성화하고 싶다면, bootstrap/app.php 파일에서 trimStrings와 convertEmptyStringsToNull 미들웨어 메서드를 사용할 수 있습니다. 각 메서드는 클로저 배열을 인수로 받으며, 클로저가 true를 반환하면 해당 요청에 대한 정규화를 건너뜁니다.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->convertEmptyStringsToNull(except: [
        fn (Request $request) => $request->is('admin/*'),
    ]);

    $middleware->trimStrings(except: [
        fn (Request $request) => $request->is('admin/*'),
    ]);
})

NOTE

위 예시는 admin/* 경로로 들어오는 요청에 대해서만 정규화를 생략합니다. 관리자 페이지처럼 사용자가 의도적으로 공백을 포함하거나 빈 값을 전송할 수 있는 경우에 유용합니다.

HTTP 요청

파일

업로드된 파일 가져오기

Illuminate\Http\Request 인스턴스의 file 메서드나 동적 프로퍼티를 사용해 업로드된 파일을 가져올 수 있습니다. file 메서드는 PHP의 SplFileInfo 클래스를 확장한 Illuminate\Http\UploadedFile 인스턴스를 반환하며, 파일을 다루는 다양한 메서드를 제공합니다.

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

$file = $request->photo;

hasFile 메서드를 사용하면 해당 파일이 요청에 포함되어 있는지 확인할 수 있습니다.

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

저장 전에 이미지를 조작해야 할 경우, image 메서드를 사용하면 Illuminate\Image\Image 인스턴스를 가져올 수 있습니다. 파일이 없으면 null을 반환합니다.

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

이미지 조작에 대한 자세한 내용은 이미지 조작 문서를 참고하세요.

업로드 성공 여부 확인

파일 존재 여부 외에도, isValid 메서드를 통해 업로드 과정에서 문제가 없었는지 검증할 수 있습니다.

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

파일 경로와 확장자

UploadedFile 클래스는 파일의 전체 경로와 확장자를 가져오는 메서드도 제공합니다. extension 메서드는 파일 내용을 기반으로 확장자를 추론합니다. 클라이언트가 전송한 확장자와 다를 수 있으니 주의하세요.

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

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

그 외 파일 관련 메서드

UploadedFile 인스턴스에는 이 외에도 다양한 메서드가 있습니다. 전체 목록은 Symfony 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으로 트래픽을 전달하기 때문에, 애플리케이션이 보안 링크를 생성해야 한다는 사실을 알지 못하기 때문입니다.

이 문제를 해결하려면 Illuminate\Http\Middleware\TrustProxies 미들웨어를 활성화하면 됩니다. bootstrap/app.php 파일에서 trustProxies 미들웨어 메서드를 사용해 신뢰할 로드 밸런서나 프록시를 지정할 수 있습니다.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: [
        '192.168.1.1',
        '10.0.0.0/8',
    ]);
})

신뢰할 프록시 IP 외에, 신뢰할 프록시 헤더도 함께 설정할 수 있습니다.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(headers: Request::HEADER_X_FORWARDED_FOR |
        Request::HEADER_X_FORWARDED_HOST |
        Request::HEADER_X_FORWARDED_PORT |
        Request::HEADER_X_FORWARDED_PROTO |
        Request::HEADER_X_FORWARDED_AWS_ELB
    );
})

NOTE

AWS Elastic Load Balancing을 사용하는 경우 headers 값으로 Request::HEADER_X_FORWARDED_AWS_ELB를 사용하세요. RFC 7239 표준의 Forwarded 헤더를 사용하는 로드 밸런서라면 Request::HEADER_FORWARDED를 사용합니다. 사용 가능한 상수 목록은 Symfony의 프록시 신뢰 설정 문서를 참고하세요.

모든 프록시 신뢰하기

Amazon AWS나 기타 클라우드 로드 밸런서 환경에서는 실제 밸런서의 IP 주소를 미리 알 수 없는 경우가 있습니다. 이런 경우 *를 사용해 모든 프록시를 신뢰하도록 설정할 수 있습니다.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

NOTE

모든 프록시를 신뢰하는 설정은 편리하지만, 클라이언트가 X-Forwarded-For 헤더를 임의로 조작할 수 있으므로 퍼블릭 인터넷에 직접 노출된 환경에서는 주의해서 사용하세요.

신뢰할 수 있는 호스트 설정

기본적으로 Laravel은 HTTP 요청의 Host 헤더 값에 관계없이 수신되는 모든 요청에 응답합니다. 또한 웹 요청 중 애플리케이션의 절대 URL을 생성할 때 Host 헤더 값이 사용됩니다.

일반적으로는 Nginx나 Apache 같은 웹 서버에서 특정 호스트명과 일치하는 요청만 애플리케이션으로 전달하도록 설정하는 것이 좋습니다. 그러나 웹 서버를 직접 수정할 수 없는 환경이라면, Laravel 자체에서 특정 호스트명의 요청만 처리하도록 Illuminate\Http\Middleware\TrustHosts 미들웨어를 활성화할 수 있습니다.

TrustHosts 미들웨어를 활성화하려면 bootstrap/app.php 파일에서 trustHosts 미들웨어 메서드를 호출하면 됩니다. at 인자에 허용할 호스트명을 지정하며, 이 값은 정규식으로 처리됩니다. 지정된 호스트명과 일치하지 않는 Host 헤더를 가진 요청은 거부됩니다.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustHosts(at: ['^laravel\.test$']);
})

기본적으로 애플리케이션 URL의 서브도메인에서 오는 요청도 자동으로 신뢰됩니다. 이 동작을 비활성화하려면 subdomains 인자를 사용하세요.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustHosts(at: ['^laravel\.test$'], subdomains: false);
})

신뢰할 호스트 목록을 설정 파일이나 데이터베이스에서 동적으로 불러와야 한다면, at 인자에 클로저를 전달할 수도 있습니다.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustHosts(at: fn () => config('app.trusted_hosts'));
})

NOTE

호스트명 문자열은 정규식으로 평가됩니다. 예를 들어 .은 임의의 문자를 의미하므로, 도메인 구분자로 사용할 때는 반드시 \.과 같이 이스케이프해야 합니다.