HTTP 응답

번역일: 2026년 6월 20일

HTTP 응답

응답 생성
리다이렉트
기타 응답 유형
응답 매크로

응답 생성

문자열과 배열

모든 라우트와 컨트롤러는 사용자의 브라우저로 돌려보낼 응답을 반환해야 합니다. Laravel은 응답을 반환하는 여러 가지 방법을 제공합니다. 가장 간단한 방법은 라우트나 컨트롤러에서 문자열을 반환하는 것입니다. 프레임워크가 자동으로 해당 문자열을 완전한 HTTP 응답으로 변환해 줍니다.

Route::get('/', function () {
    return 'Hello World';
});

문자열뿐만 아니라 배열을 반환할 수도 있습니다. 배열을 반환하면 프레임워크가 자동으로 JSON 응답으로 변환합니다.

Route::get('/', function () {
    return [1, 2, 3];
});

NOTE

라우트나 컨트롤러에서 Eloquent 컬렉션을 직접 반환할 수도 있습니다. 컬렉션도 자동으로 JSON으로 변환됩니다.

Response 객체

실제 프로젝트에서는 단순한 문자열이나 배열 대신, 완전한 Illuminate\Http\Response 인스턴스나 뷰를 반환하는 경우가 많습니다.

Response 인스턴스를 반환하면 HTTP 상태 코드와 헤더를 직접 지정할 수 있습니다. Response는 Symfony\Component\HttpFoundation\Response를 상속하므로 HTTP 응답을 구성하는 다양한 메서드를 사용할 수 있습니다.

Route::get('/home', function () {
    return response('Hello World', 200)
                  ->header('Content-Type', 'text/plain');
});

Eloquent 모델과 컬렉션

Eloquent ORM 모델이나 컬렉션을 라우트 또는 컨트롤러에서 직접 반환할 수도 있습니다. 이 경우 Laravel은 모델의 숨김 속성을 올바르게 처리하면서 자동으로 JSON 응답으로 변환합니다.

use App\Models\User;

Route::get('/user/{user}', function (User $user) {
    return $user;
});

응답에 헤더 추가하기

대부분의 응답 메서드는 메서드 체이닝을 지원하므로, 응답 인스턴스를 유연하게 구성할 수 있습니다. 예를 들어 header 메서드를 연속으로 호출해 여러 헤더를 추가할 수 있습니다.

return response($content)
            ->header('Content-Type', $type)
            ->header('X-Header-One', 'Header Value')
            ->header('X-Header-Two', 'Header Value');

여러 헤더를 한 번에 추가할 때는 withHeaders 메서드에 배열을 전달하는 방식이 더 편리합니다.

return response($content)
            ->withHeaders([
                'Content-Type' => $type,
                'X-Header-One' => 'Header Value',
                'X-Header-Two' => 'Header Value',
            ]);

Cache Control 미들웨어

Laravel에는 라우트 그룹에 Cache-Control 헤더를 손쉽게 적용할 수 있는 cache.headers 미들웨어가 내장되어 있습니다. 캐시 제어 디렉티브는 스네이크 케이스로 작성하고 세미콜론(;)으로 구분합니다. etag를 지정하면 응답 내용의 MD5 해시가 ETag 식별자로 자동 설정됩니다.

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/privacy', function () {
        // ...
    });

    Route::get('/terms', function () {
        // ...
    });
});

응답에 쿠키 추가하기

Illuminate\Http\Response 인스턴스의 cookie 메서드를 사용해 응답에 쿠키를 추가할 수 있습니다. 쿠키 이름, 값, 유효 기간(분 단위)을 인수로 전달합니다.

return response('Hello World')->cookie(
    'name', 'value', $minutes
);

cookie 메서드는 PHP 기본 함수 setcookie와 동일한 역할을 하는 추가 인수도 지원합니다.

return response('Hello World')->cookie(
    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
);

응답 인스턴스가 아직 없는 상황에서 쿠키를 미리 등록해야 한다면, Cookie 파사드의 queue 메서드를 사용하세요. 이렇게 등록된 쿠키는 응답이 브라우저로 전송되기 전에 자동으로 첨부됩니다.

use Illuminate\Support\Facades\Cookie;

Cookie::queue('name', 'value', $minutes);

나중에 응답에 첨부하기 위해 Symfony\Component\HttpFoundation\Cookie 인스턴스를 미리 만들어 두려면 전역 cookie 헬퍼를 사용하세요. 이 쿠키는 응답 인스턴스에 실제로 첨부되기 전까지 클라이언트로 전송되지 않습니다.

$cookie = cookie('name', 'value', $minutes);

return response('Hello World')->cookie($cookie);

쿠키 즉시 만료시키기

응답의 withoutCookie 메서드를 사용하면 쿠키를 만료시켜 삭제할 수 있습니다.

return response('Hello World')->withoutCookie('name');

응답 인스턴스가 없는 경우에는 Cookie 파사드의 expire 메서드를 사용하세요.

Cookie::expire('name');

쿠키와 암호화

Laravel이 생성하는 모든 쿠키는 기본적으로 암호화 및 서명 처리되므로, 클라이언트 측에서 임의로 읽거나 변조할 수 없습니다. 특정 쿠키에 대해 암호화를 비활성화하려면 app/Http/Middleware 디렉터리의 App\Http\Middleware\EncryptCookies 미들웨어에 있는 $except 속성을 사용하세요.

/**
 * 암호화하지 않을 쿠키 이름 목록
 *
 * @var array
 */
protected $except = [
    'cookie_name',
];

리다이렉트

리다이렉트 응답은 Illuminate\Http\RedirectResponse 클래스의 인스턴스이며, 사용자를 다른 URL로 이동시키는 데 필요한 헤더를 포함합니다. 가장 간단한 방법은 전역 redirect 헬퍼를 사용하는 것입니다.

Route::get('/dashboard', function () {
    return redirect('home/dashboard');
});

폼 유효성 검사 실패 등의 상황에서 사용자를 이전 페이지로 돌려보내야 할 때는 전역 back 헬퍼를 사용하세요. 이 기능은 세션을 활용하므로, back 함수를 호출하는 라우트가 반드시 web 미들웨어 그룹에 속해야 합니다.

Route::post('/user/profile', function () {
    // 요청 유효성 검사...

    return back()->withInput();
});

이름이 지정된 라우트로 리다이렉트

redirect 헬퍼를 인수 없이 호출하면 Illuminate\Routing\Redirector 인스턴스가 반환됩니다. 이 인스턴스의 route 메서드를 사용하면 이름이 지정된 라우트로 리다이렉트할 수 있습니다.

return redirect()->route('login');

라우트에 파라미터가 있는 경우 두 번째 인수로 전달합니다.

// URI가 /profile/{id}인 라우트로 리다이렉트

return redirect()->route('profile', ['id' => 1]);

Eloquent 모델로 라우트 파라미터 채우기

ID 파라미터를 Eloquent 모델에서 가져와야 하는 경우, 모델 인스턴스를 그대로 전달하면 자동으로 ID 값이 추출됩니다.

// URI가 /profile/{id}인 라우트로 리다이렉트

return redirect()->route('profile', [$user]);

라우트 파라미터에 사용할 값을 커스터마이징하려면, 라우트 파라미터 정의에서 컬럼을 지정하거나(/profile/{id:slug}), Eloquent 모델의 getRouteKey 메서드를 오버라이드하세요.

/**
 * 모델의 라우트 키 값을 반환합니다.
 */
public function getRouteKey(): mixed
{
    return $this->slug;
}

컨트롤러 액션으로 리다이렉트

컨트롤러 액션으로 직접 리다이렉트하려면 action 메서드에 컨트롤러 클래스와 메서드 이름을 전달합니다.

use App\Http\Controllers\UserController;

return redirect()->action([UserController::class, 'index']);

컨트롤러 라우트에 파라미터가 필요한 경우 두 번째 인수로 전달합니다.

return redirect()->action(
    [UserController::class, 'profile'], ['id' => 1]
);

외부 도메인으로 리다이렉트

애플리케이션 외부 도메인으로 리다이렉트할 때는 away 메서드를 사용하세요. 이 메서드는 URL 인코딩, 유효성 검사, 추가 검증 없이 RedirectResponse를 생성합니다.

return redirect()->away('https://www.google.com');

세션 플래시 데이터와 함께 리다이렉트

리다이렉트와 세션 플래시 데이터 저장은 주로 함께 사용됩니다. 예를 들어 작업이 성공적으로 완료된 후 성공 메시지를 세션에 저장하는 패턴이 일반적입니다. RedirectResponse 인스턴스에서 메서드 체이닝을 통해 리다이렉트와 플래시 데이터 저장을 한 번에 처리할 수 있습니다.

Route::post('/user/profile', function () {
    // ...

    return redirect('dashboard')->with('status', '프로필이 업데이트되었습니다!');
});

리다이렉트 후 Blade 문법으로 플래시 메시지를 표시할 수 있습니다.

@if (session('status'))
    <div class="alert alert-success">
        {{ session('status') }}
    </div>
@endif

입력값과 함께 리다이렉트

유효성 검사 오류가 발생했을 때 사용자가 입력한 값을 세션에 플래시한 뒤 이전 페이지로 돌려보내야 하는 경우가 많습니다. withInput 메서드를 사용하면 현재 요청의 입력값을 세션에 저장할 수 있으며, 다음 요청에서 이전 입력값을 가져와 폼을 다시 채울 수 있습니다.

return back()->withInput();

기타 응답 유형

response 헬퍼를 인수 없이 호출하면 Illuminate\Contracts\Routing\ResponseFactory 컨트랙트 구현체가 반환됩니다. 이 구현체는 다양한 유형의 응답을 생성하는 편리한 메서드를 제공합니다.

뷰 응답

HTTP 상태 코드와 헤더를 직접 지정하면서 뷰를 응답 내용으로 반환해야 할 때는 view 메서드를 사용하세요.

return response()
            ->view('hello', $data, 200)
            ->header('Content-Type', $type);

커스텀 상태 코드나 헤더가 필요하지 않다면 전역 view 헬퍼 함수를 바로 사용해도 됩니다.

JSON 응답

json 메서드는 Content-Type 헤더를 자동으로 application/json으로 설정하고, 전달받은 배열을 json_encode 함수를 이용해 JSON으로 변환합니다.

return response()->json([
    'name' => '홍길동',
    'state' => '서울',
]);

JSONP 응답이 필요하다면 json 메서드와 withCallback 메서드를 함께 사용하세요.

return response()
            ->json(['name' => '홍길동', 'state' => '서울'])
            ->withCallback($request->input('callback'));

파일 다운로드

download 메서드는 지정한 경로의 파일을 강제로 다운로드하도록 브라우저에 지시하는 응답을 생성합니다. 두 번째 인수로 다운로드 시 표시될 파일명을, 세 번째 인수로 HTTP 헤더 배열을 전달할 수 있습니다.

return response()->download($pathToFile);

return response()->download($pathToFile, $name, $headers);

WARNING

파일 다운로드를 처리하는 Symfony HttpFoundation은 파일명이 ASCII 문자여야 합니다. 한글 파일명을 사용할 경우 인코딩 문제가 발생할 수 있으므로 주의하세요.

스트림 다운로드

작업의 결과 문자열을 디스크에 파일로 저장하지 않고 바로 다운로드 응답으로 전환하고 싶을 때는 streamDownload 메서드를 사용하세요. 콜백, 파일명, 선택적 헤더 배열을 인수로 받습니다.

use App\Services\GitHub;

return response()->streamDownload(function () {
    echo GitHub::api('repo')
                ->contents()
                ->readme('laravel', 'laravel')['contents'];
}, 'laravel-readme.md');

파일 응답

file 메서드를 사용하면 이미지나 PDF 같은 파일을 다운로드 대신 브라우저에서 바로 열어서 표시할 수 있습니다. 첫 번째 인수로 파일의 절대 경로를, 두 번째 인수로 헤더 배열을 전달합니다.

return response()->file($pathToFile);

return response()->file($pathToFile, $headers);

응답 매크로

여러 라우트와 컨트롤러에서 재사용할 커스텀 응답을 정의하고 싶다면, Response 파사드의 macro 메서드를 사용하세요. 매크로는 일반적으로 App\Providers\AppServiceProvider와 같은 서비스 프로바이더의 boot 메서드에서 등록합니다.

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 애플리케이션 서비스를 부트스트랩합니다.
     */
    public function boot(): void
    {
        Response::macro('caps', function (string $value) {
            return Response::make(strtoupper($value));
        });
    }
}

macro 함수는 첫 번째 인수로 매크로 이름, 두 번째 인수로 클로저를 받습니다. 등록된 매크로는 ResponseFactory 구현체나 response 헬퍼를 통해 호출할 수 있습니다.

return response()->caps('foo');

HTTP 응답

응답 생성

문자열과 배열

Response 객체

Eloquent 모델과 컬렉션

응답에 헤더 추가하기

Cache Control 미들웨어

응답에 쿠키 추가하기

쿠키 인스턴스 생성하기

쿠키 즉시 만료시키기

쿠키와 암호화

리다이렉트

이름이 지정된 라우트로 리다이렉트

Eloquent 모델로 라우트 파라미터 채우기

컨트롤러 액션으로 리다이렉트

외부 도메인으로 리다이렉트

세션 플래시 데이터와 함께 리다이렉트

입력값과 함께 리다이렉트

기타 응답 유형

뷰 응답

JSON 응답

파일 다운로드

스트림 다운로드

파일 응답

응답 매크로