세션

번역일: 2026년 6월 20일

세션

소개
- 설정
- 드라이버 사전 준비
세션 데이터 다루기
세션 블로킹
커스텀 세션 드라이버 추가
- 드라이버 구현
- 드라이버 등록

소개

HTTP는 기본적으로 상태를 유지하지 않는(stateless) 프로토콜입니다. 세션은 이 한계를 보완하여, 여러 요청에 걸쳐 사용자 정보를 지속적으로 유지할 수 있게 해주는 메커니즘입니다. 세션 데이터는 서버 측의 영속적인 저장소에 보관되며, 이후 요청에서도 동일한 데이터에 접근할 수 있습니다.

Laravel은 통일된 API를 통해 다양한 세션 백엔드를 지원합니다. Memcached, Redis, 데이터베이스 등 널리 사용되는 백엔드를 기본으로 제공합니다.

설정

세션 설정 파일은 config/session.php에 위치합니다. 이 파일에서 사용할 수 있는 옵션들을 살펴보세요. Laravel은 기본적으로 file 세션 드라이버를 사용하도록 설정되어 있으며, 대부분의 애플리케이션에서 잘 작동합니다. 다만, 여러 웹 서버에 걸쳐 로드 밸런싱을 적용하는 환경이라면, 모든 서버가 공유할 수 있는 중앙 집중식 저장소(Redis나 데이터베이스 등)를 선택해야 합니다.

driver 설정 옵션은 각 요청마다 세션 데이터를 어디에 저장할지 결정합니다. Laravel이 기본으로 제공하는 드라이버는 다음과 같습니다.

file - storage/framework/sessions 디렉터리에 세션을 저장합니다.
cookie - 암호화된 쿠키에 세션을 저장합니다.
database - 관계형 데이터베이스에 세션을 저장합니다.
memcached / redis - 빠른 캐시 기반 저장소에 세션을 저장합니다.
dynamodb - AWS DynamoDB에 세션을 저장합니다.
array - PHP 배열에 세션을 저장하며, 데이터가 영속되지 않습니다.

NOTE

array 드라이버는 주로 테스트 환경에서 사용하며, 세션 데이터가 실제로 저장되지 않습니다.

드라이버 사전 준비

Database

database 세션 드라이버를 사용하려면 세션 데이터를 저장할 테이블이 필요합니다. 아래는 해당 테이블을 생성하는 Schema 선언 예시입니다.

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('sessions', function (Blueprint $table) {
    $table->string('id')->primary();
    $table->foreignId('user_id')->nullable()->index();
    $table->string('ip_address', 45)->nullable();
    $table->text('user_agent')->nullable();
    $table->text('payload');
    $table->integer('last_activity')->index();
});

session:table Artisan 명령어를 실행하면 이 마이그레이션 파일을 자동으로 생성할 수 있습니다. 마이그레이션에 대한 자세한 내용은 마이그레이션 문서를 참고하세요.

php artisan session:tablephp artisan migrate

Redis

Laravel에서 Redis 세션을 사용하려면, PECL을 통해 PhpRedis PHP 확장을 설치하거나 Composer로 predis/predis 패키지(~1.0)를 설치해야 합니다. Redis 설정에 대한 자세한 내용은 Redis 문서를 참고하세요.

NOTE

session 설정 파일의 connection 옵션을 사용하면 세션에서 사용할 Redis 커넥션을 지정할 수 있습니다.

세션 데이터 다루기

데이터 조회

Laravel에서 세션 데이터를 다루는 방법은 크게 두 가지입니다. 전역 session 헬퍼를 사용하는 방법과, Request 인스턴스를 통해 접근하는 방법입니다. 먼저 Request 인스턴스를 사용하는 방법을 살펴보겠습니다. 라우트 클로저나 컨트롤러 메서드에서 타입 힌트로 Request를 선언하면, Laravel 서비스 컨테이너가 자동으로 주입해줍니다.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 주어진 사용자의 프로필을 표시합니다.
     */
    public function show(Request $request, string $id): View
    {
        $value = $request->session()->get('key');

        // ...

        $user = $this->users->find($id);

        return view('user.profile', ['user' => $user]);
    }
}

get 메서드의 두 번째 인자로 기본값을 전달할 수 있습니다. 지정한 키가 세션에 존재하지 않으면 이 기본값이 반환됩니다. 기본값으로 클로저를 전달하면, 키가 존재하지 않을 때 클로저가 실행되어 그 반환값이 사용됩니다.

$value = $request->session()->get('key', 'default');

$value = $request->session()->get('key', function () {
    return 'default';
});

전역 Session 헬퍼

전역 session 함수를 사용해 세션 데이터를 조회하거나 저장할 수도 있습니다. 문자열 인자 하나를 전달하면 해당 키의 값을 반환하고, 키/값 쌍의 배열을 전달하면 세션에 데이터를 저장합니다.

Route::get('/home', function () {
    // 세션에서 데이터 조회
    $value = session('key');

    // 기본값 지정
    $value = session('key', 'default');

    // 세션에 데이터 저장
    session(['key' => 'value']);
});

NOTE

HTTP 요청 인스턴스를 통해 세션에 접근하는 방법과 전역 session 헬퍼를 사용하는 방법 사이에는 실질적인 차이가 없습니다. 두 방법 모두 테스트 케이스에서 assertSessionHas 메서드를 통해 테스트할 수 있습니다.

모든 세션 데이터 조회

세션에 저장된 모든 데이터를 가져오려면 all 메서드를 사용하세요.

$data = $request->session()->all();

일부 세션 데이터 조회

only 메서드와 except 메서드를 사용하면 세션 데이터의 일부만 선택적으로 가져올 수 있습니다.

$data = $request->session()->only(['username', 'email']);

$data = $request->session()->except(['username', 'email']);

세션 키 존재 여부 확인

세션에 특정 항목이 존재하는지 확인하려면 has 메서드를 사용합니다. 값이 존재하고 null이 아닌 경우에만 true를 반환합니다.

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

값이 null이더라도 키 자체가 존재하는지 확인하고 싶다면 exists 메서드를 사용합니다.

if ($request->session()->exists('users')) {
    // ...
}

반대로, 특정 항목이 세션에 존재하지 않는지 확인하려면 missing 메서드를 사용합니다. 항목이 없을 때 true를 반환합니다.

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

데이터 저장

세션에 데이터를 저장할 때는 주로 요청 인스턴스의 put 메서드나 전역 session 헬퍼를 사용합니다.

// 요청 인스턴스를 통해 저장
$request->session()->put('key', 'value');

// 전역 "session" 헬퍼를 통해 저장
session(['key' => 'value']);

배열 세션 값에 요소 추가

세션에 저장된 값이 배열인 경우, push 메서드로 새 값을 추가할 수 있습니다. 예를 들어 user.teams 키에 팀 이름 배열이 저장되어 있다면 다음과 같이 새 팀을 추가할 수 있습니다.

$request->session()->push('user.teams', 'developers');

조회 후 삭제

pull 메서드는 세션에서 값을 조회하고 동시에 삭제합니다. 한 번만 사용할 일회성 데이터에 유용합니다.

$value = $request->session()->pull('key', 'default');

세션 값 증가 및 감소

세션에 저장된 값이 정수인 경우, increment와 decrement 메서드로 값을 증감할 수 있습니다.

$request->session()->increment('count');

$request->session()->increment('count', $incrementBy = 2);

$request->session()->decrement('count');

$request->session()->decrement('count', $decrementBy = 2);

Flash 데이터

다음 요청에서만 사용할 데이터를 세션에 잠시 저장하고 싶을 때는 flash 메서드를 사용합니다. flash로 저장된 데이터는 현재 요청과 바로 다음 요청에서 사용할 수 있으며, 그 이후에는 자동으로 삭제됩니다. Flash 데이터는 주로 한 번만 표시하는 상태 메시지(예: "저장되었습니다", "오류가 발생했습니다")에 적합합니다.

$request->session()->flash('status', '작업이 성공적으로 완료되었습니다!');

Flash 데이터를 여러 요청에 걸쳐 유지해야 한다면 reflash 메서드를 사용합니다. 특정 데이터만 유지하려면 keep 메서드에 키를 지정하세요.

$request->session()->reflash();

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

현재 요청에서만 Flash 데이터를 사용하려면 now 메서드를 사용합니다.

$request->session()->now('status', '작업이 성공적으로 완료되었습니다!');

데이터 삭제

특정 키의 데이터를 삭제하려면 forget 메서드를 사용합니다. 세션의 모든 데이터를 삭제하려면 flush 메서드를 사용하세요.

// 단일 키 삭제
$request->session()->forget('name');

// 여러 키 삭제
$request->session()->forget(['name', 'status']);

// 모든 세션 데이터 삭제
$request->session()->flush();

세션 ID 재생성

세션 ID를 재생성하는 것은 세션 고정(Session Fixation) 공격을 방지하기 위한 중요한 보안 조치입니다.

Laravel 애플리케이션 스타터 키트나 Laravel Fortify를 사용하고 있다면, 인증 과정에서 세션 ID가 자동으로 재생성됩니다. 수동으로 세션 ID를 재생성해야 하는 경우에는 regenerate 메서드를 사용하세요.

$request->session()->regenerate();

세션 ID를 재생성하면서 모든 데이터를 동시에 삭제하려면 invalidate 메서드를 사용합니다.

$request->session()->invalidate();

세션 블로킹

WARNING

세션 블로킹을 사용하려면 원자적 잠금(Atomic Locks)을 지원하는 캐시 드라이버가 필요합니다. 현재 지원되는 드라이버는 memcached, dynamodb, redis, database, file, array입니다. cookie 세션 드라이버와는 함께 사용할 수 없습니다.

기본적으로 Laravel은 동일한 세션을 사용하는 요청들이 동시에 실행되는 것을 허용합니다. 예를 들어 JavaScript HTTP 라이브러리로 두 개의 요청을 동시에 보내면 두 요청이 병렬로 처리됩니다. 대부분의 경우 이는 문제가 없지만, 서로 다른 두 엔드포인트가 동시에 세션에 데이터를 쓰는 경우 세션 데이터 손실이 발생할 수 있습니다.

이 문제를 방지하기 위해 Laravel은 특정 세션에 대한 동시 요청을 제한하는 세션 블로킹 기능을 제공합니다. 라우트 정의에 block 메서드를 체인하면 됩니다. 아래 예시에서 /profile 엔드포인트에 요청이 들어오면 세션 잠금을 획득합니다. 이 잠금이 유지되는 동안, 동일한 세션 ID를 가진 /profile 또는 /order 요청은 첫 번째 요청이 완료될 때까지 대기합니다.

Route::post('/profile', function () {
    // ...
})->block($lockSeconds = 10, $waitSeconds = 10)

Route::post('/order', function () {
    // ...
})->block($lockSeconds = 10, $waitSeconds = 10)

block 메서드는 두 개의 선택적 인자를 받습니다.

첫 번째 인자: 세션 잠금을 최대 몇 초 동안 유지할지 지정합니다. 요청이 그 이전에 완료되면 잠금이 일찍 해제됩니다.
두 번째 인자: 세션 잠금을 얻기 위해 요청이 최대 몇 초 동안 대기할지 지정합니다. 지정한 시간 내에 잠금을 획득하지 못하면 Illuminate\Contracts\Cache\LockTimeoutException이 발생합니다.

인자를 전달하지 않으면 기본값으로 최대 10초 동안 잠금을 유지하고, 10초 동안 잠금 획득을 시도합니다.

Route::post('/profile', function () {
    // ...
})->block()

커스텀 세션 드라이버 추가

드라이버 구현

기본 제공 세션 드라이버가 요구사항을 충족하지 못한다면, 직접 세션 핸들러를 구현할 수 있습니다. 커스텀 세션 드라이버는 PHP 내장 인터페이스인 SessionHandlerInterface를 구현해야 합니다. 아래는 MongoDB를 사용하는 구현 예시입니다.

<?php

namespace App\Extensions;

class MongoSessionHandler implements \SessionHandlerInterface
{
    public function open($savePath, $sessionName) {}
    public function close() {}
    public function read($sessionId) {}
    public function write($sessionId, $data) {}
    public function destroy($sessionId) {}
    public function gc($lifetime) {}
}

NOTE

Laravel은 확장 클래스를 위한 별도의 디렉터리를 제공하지 않습니다. 원하는 위치에 자유롭게 파일을 배치하세요. 위 예시에서는 MongoSessionHandler를 App\Extensions 디렉터리에 배치했습니다.

각 메서드의 역할은 다음과 같습니다.

open - 주로 파일 기반 세션 저장소에서 사용합니다. Laravel의 file 드라이버가 이를 처리하므로, 대부분의 경우 이 메서드는 비워두어도 됩니다.
close - open과 마찬가지로 대부분의 드라이버에서 특별한 구현이 필요 없습니다.
read - 주어진 $sessionId에 해당하는 세션 데이터를 문자열로 반환합니다. 직렬화나 인코딩은 Laravel이 자동으로 처리하므로 별도로 구현할 필요가 없습니다.
write - 주어진 $sessionId에 해당하는 $data 문자열을 MongoDB 등의 영속 저장소에 기록합니다. 직렬화는 Laravel이 이미 처리했으므로 별도로 처리하지 않아도 됩니다.
destroy - 주어진 $sessionId에 해당하는 데이터를 영속 저장소에서 삭제합니다.
gc - 주어진 $lifetime(UNIX 타임스탬프)보다 오래된 세션 데이터를 모두 삭제합니다. Memcached, Redis처럼 자체 만료 기능을 가진 저장소에서는 이 메서드를 비워두어도 됩니다.

드라이버 등록

드라이버 구현이 완료되면, Laravel에 등록해야 합니다. Session 파사드의 extend 메서드를 사용하면 됩니다. 이 메서드는 서비스 프로바이더의 boot 메서드에서 호출해야 합니다. 기존의 App\Providers\AppServiceProvider에 추가하거나, 별도의 서비스 프로바이더를 새로 만들어도 됩니다.

<?php

namespace App\Providers;

use App\Extensions\MongoSessionHandler;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Session;
use Illuminate\Support\ServiceProvider;

class SessionServiceProvider extends ServiceProvider
{
    /**
     * 애플리케이션 서비스를 등록합니다.
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 애플리케이션 서비스를 부트스트랩합니다.
     */
    public function boot(): void
    {
        Session::extend('mongo', function (Application $app) {
            // SessionHandlerInterface 구현체를 반환합니다.
            return new MongoSessionHandler;
        });
    }
}

드라이버를 등록한 후에는 config/session.php 설정 파일에서 driver 값을 mongo로 설정하여 사용할 수 있습니다.