유효성 검사

번역일: 2026년 6월 20일

유효성 검사

소개
빠른 시작
Form Request 유효성 검사
수동으로 Validator 생성하기
검증된 입력 데이터 활용
오류 메시지 활용
사용 가능한 유효성 검사 규칙
조건부 규칙 추가
배열 유효성 검사
- 중첩 배열 입력 유효성 검사
- 오류 메시지의 인덱스와 위치
파일 유효성 검사
비밀번호 유효성 검사
커스텀 유효성 검사 규칙

소개

Laravel은 애플리케이션으로 들어오는 데이터를 검증하는 다양한 방법을 제공합니다. 가장 일반적인 방법은 HTTP 요청 객체에 있는 validate 메서드를 사용하는 것입니다. 이 문서에서는 이 방법을 중심으로, 그 외의 검증 방식도 함께 살펴봅니다.

Laravel에는 데이터베이스 테이블의 고유값 여부 확인을 포함해 다양한 내장 유효성 검사 규칙이 준비되어 있습니다. 각 규칙을 상세히 다루어 Laravel의 유효성 검사 기능을 충분히 익힐 수 있도록 설명합니다.

빠른 시작

Laravel 유효성 검사의 전체 흐름을 폼 제출과 오류 표시 예시를 통해 살펴보겠습니다. 이 예시를 읽고 나면 들어오는 요청 데이터를 검증하는 방법을 전반적으로 이해할 수 있습니다.

라우트 정의

먼저 routes/web.php에 다음과 같은 라우트가 정의되어 있다고 가정합니다.

use App\Http\Controllers\PostController;

Route::get('/post/create', [PostController::class, 'create']);
Route::post('/post', [PostController::class, 'store']);

GET 라우트는 새 글 작성 폼을 보여주고, POST 라우트는 새 글을 데이터베이스에 저장합니다.

컨트롤러 생성

다음으로 이 라우트를 처리하는 간단한 컨트롤러를 살펴봅니다. store 메서드는 지금은 비워 두겠습니다.

<?php

namespace App\Http\Controllers;

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

class PostController extends Controller
{
    /**
     * 새 블로그 글 작성 폼을 표시합니다.
     */
    public function create(): View
    {
        return view('post.create');
    }

    /**
     * 새 블로그 글을 저장합니다.
     */
    public function store(Request $request): RedirectResponse
    {
        // 유효성 검사 후 글을 저장합니다...

        $post = /** ... */

        return to_route('post.show', ['post' => $post->id]);
    }
}

유효성 검사 로직 작성

이제 store 메서드에 유효성 검사 로직을 추가할 준비가 됐습니다. Illuminate\Http\Request 객체가 제공하는 validate 메서드를 사용합니다. 검사를 통과하면 코드가 계속 실행되고, 실패하면 Illuminate\Validation\ValidationException 예외가 발생하며 적절한 오류 응답이 자동으로 반환됩니다.

일반적인 HTTP 요청에서 검사가 실패하면 이전 URL로 리다이렉트되고, XHR 요청에서 실패하면 유효성 검사 오류가 담긴 JSON 응답이 반환됩니다.

store 메서드에 validate를 적용한 예시입니다.

/**
 * 새 블로그 글을 저장합니다.
 */
public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'title' => 'required|unique:posts|max:255',
        'body' => 'required',
    ]);

    // 글이 유효합니다...

    return redirect('/posts');
}

규칙은 |로 구분된 문자열 대신 배열로도 작성할 수 있습니다.

$validatedData = $request->validate([
    'title' => ['required', 'unique:posts', 'max:255'],
    'body' => ['required'],
]);

validateWithBag 메서드를 사용하면 오류 메시지를 이름 있는 오류 백에 저장할 수도 있습니다.

$validatedData = $request->validateWithBag('post', [
    'title' => ['required', 'unique:posts', 'max:255'],
    'body' => ['required'],
]);

첫 번째 실패 시 검사 중단

특정 필드에서 첫 번째 규칙이 실패하면 이후 규칙을 검사하지 않으려면 bail 규칙을 추가하세요.

$request->validate([
    'title' => 'bail|required|unique:posts|max:255',
    'body' => 'required',
]);

이 예시에서 title 필드의 unique 규칙이 실패하면 max 규칙은 검사하지 않습니다. 규칙은 정의된 순서대로 검사됩니다.

중첩 필드 참고사항

HTTP 요청에 중첩된 필드 데이터가 있다면 "점(dot) 표기법"으로 지정할 수 있습니다.

$request->validate([
    'title' => 'required|unique:posts|max:255',
    'author.name' => 'required',
    'author.description' => 'required',
]);

필드명 자체에 점(.)이 포함된 경우에는 백슬래시로 이스케이프하여 점 표기법으로 해석되지 않도록 합니다.

$request->validate([
    'title' => 'required|unique:posts|max:255',
    'v1\.0' => 'required',
]);

유효성 검사 오류 표시

요청 데이터가 검사를 통과하지 못하면 Laravel이 자동으로 이전 페이지로 리다이렉트합니다. 이때 모든 유효성 검사 오류와 요청 입력값이 세션에 플래시됩니다.

web 미들웨어 그룹에 포함된 Illuminate\View\Middleware\ShareErrorsFromSession 미들웨어가 $errors 변수를 모든 뷰와 자동으로 공유합니다. 이 미들웨어가 적용된 상태에서는 $errors 변수가 항상 사용 가능하므로 안전하게 사용할 수 있습니다. $errors는 Illuminate\Support\MessageBag 인스턴스입니다. 자세한 내용은 오류 메시지 활용 섹션을 참고하세요.

검사가 실패하면 사용자는 컨트롤러의 create 메서드로 리다이렉트되어 뷰에서 오류 메시지를 확인할 수 있습니다.

<!-- /resources/views/post/create.blade.php -->

<h1>새 글 작성</h1>

@if ($errors->any())
    <div class="alert alert-danger">
        <ul>
            @foreach ($errors->all() as $error)
                <li>{{ $error }}</li>
            @endforeach
        </ul>
    </div>
@endif

<!-- 글 작성 폼 -->

오류 메시지 커스터마이징

Laravel 내장 유효성 검사 규칙의 오류 메시지는 lang/en/validation.php 파일에 있습니다. 애플리케이션에 lang 디렉터리가 없다면 lang:publish Artisan 명령어로 생성할 수 있습니다.

php artisan lang:publish

이 파일에서 각 규칙의 메시지를 자유롭게 변경할 수 있습니다. 한국어 메시지를 제공하려면 lang/ko/validation.php 파일을 만들어 번역하세요. Laravel 현지화에 대한 자세한 내용은 현지화 문서를 참고하세요.

WARNING

기본적으로 Laravel 애플리케이션 스켈레톤에는 lang 디렉터리가 포함되지 않습니다. 언어 파일을 커스터마이징하려면 lang:publish Artisan 명령어로 발행하세요.

XHR 요청과 유효성 검사

위 예시에서는 일반 HTML 폼으로 데이터를 전송했지만, JavaScript 프론트엔드에서 XHR 요청을 보내는 경우도 많습니다. XHR 요청에서 validate 메서드를 사용하면 리다이렉트 대신 유효성 검사 오류가 담긴 JSON 응답이 HTTP 422 상태 코드와 함께 반환됩니다.

`@error` 디렉티브

Blade의 @error 디렉티브를 사용하면 특정 필드에 유효성 검사 오류가 있는지 간편하게 확인할 수 있습니다. @error 블록 안에서 $message 변수로 오류 메시지를 출력할 수 있습니다.

<!-- /resources/views/post/create.blade.php -->

<label for="title">글 제목</label>

<input
    id="title"
    type="text"
    name="title"
    class="@error('title') is-invalid @enderror"
/>

@error('title')
    <div class="alert alert-danger">{{ $message }}</div>
@enderror

이름 있는 오류 백을 사용하는 경우, 오류 백 이름을 두 번째 인수로 전달할 수 있습니다.

<input ... class="@error('title', 'post') is-invalid @enderror">

폼 값 복원

유효성 검사 실패로 리다이렉트가 발생하면 Laravel은 모든 요청 입력값을 세션에 자동으로 플래시합니다. 이를 통해 다음 요청에서 이전에 입력했던 값을 불러와 폼을 복원할 수 있습니다.

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

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

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

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

선택 필드 참고사항

Laravel은 기본적으로 전역 미들웨어 스택에 TrimStrings와 ConvertEmptyStringsToNull 미들웨어를 포함합니다. 이 때문에 null 값을 유효하지 않은 값으로 처리하지 않으려면 선택적 필드에 nullable 규칙을 추가해야 합니다.

$request->validate([
    'title' => 'required|unique:posts|max:255',
    'body' => 'required',
    'publish_at' => 'nullable|date',
]);

이 예시에서 publish_at 필드는 null이거나 유효한 날짜 형식이어야 합니다. nullable을 추가하지 않으면 null 값이 유효하지 않은 날짜로 처리됩니다.

유효성 검사 오류 응답 형식

애플리케이션이 Illuminate\Validation\ValidationException 예외를 던지고, 들어오는 요청이 JSON 응답을 기대하는 경우 Laravel은 오류 메시지를 자동으로 포맷하여 422 Unprocessable Entity HTTP 응답을 반환합니다.

유효성 검사 오류의 JSON 응답 예시는 다음과 같습니다. 중첩된 오류 키는 "점 표기법"으로 평탄화됩니다.

{
    "message": "The team name must be a string. (and 4 more errors)",
    "errors": {
        "team_name": [
            "The team name must be a string.",
            "The team name must be at least 1 characters."
        ],
        "authorization.role": [
            "The selected authorization.role is invalid."
        ],
        "users.0.email": [
            "The users.0.email field is required."
        ],
        "users.2.email": [
            "The users.2.email must be a valid email address."
        ]
    }
}

Form Request 유효성 검사

Form Request 생성

복잡한 유효성 검사 시나리오에서는 "Form Request"를 사용하는 것이 좋습니다. Form Request는 유효성 검사와 권한 검사 로직을 자체적으로 담고 있는 커스텀 요청 클래스입니다. make:request Artisan 명령어로 Form Request 클래스를 생성할 수 있습니다.

php artisan make:request StorePostRequest

생성된 Form Request 클래스는 app/Http/Requests 디렉터리에 위치합니다. 이 디렉터리가 없으면 명령 실행 시 자동으로 만들어집니다. 각 Form Request에는 authorize와 rules 두 메서드가 있습니다.

authorize 메서드는 현재 인증된 사용자가 해당 요청을 수행할 권한이 있는지 판단하고, rules 메서드는 요청 데이터에 적용할 유효성 검사 규칙을 반환합니다.

/**
 * 요청에 적용할 유효성 검사 규칙을 반환합니다.
 *
 * @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
 */
public function rules(): array
{
    return [
        'title' => 'required|unique:posts|max:255',
        'body' => 'required',
    ];
}

NOTE

rules 메서드 시그니처에 의존성을 타입힌트로 선언하면 Laravel 서비스 컨테이너가 자동으로 해결해 줍니다.

유효성 검사 규칙은 어떻게 실행될까요? 컨트롤러 메서드에서 Form Request를 타입힌트로 선언하기만 하면 됩니다. 컨트롤러 메서드가 호출되기 전에 요청이 자동으로 검증되므로, 컨트롤러에 검사 로직을 넣지 않아도 됩니다.

/**
 * 새 블로그 글을 저장합니다.
 */
public function store(StorePostRequest $request): RedirectResponse
{
    // 요청이 유효합니다...

    // 검증된 입력 데이터를 가져옵니다...
    $validated = $request->validated();

    // 검증된 데이터의 일부만 가져옵니다...
    $validated = $request->safe()->only(['name', 'email']);
    $validated = $request->safe()->except(['name', 'email']);

    // 블로그 글을 저장합니다...

    return redirect('/posts');
}

검사가 실패하면 이전 위치로 리다이렉트되고, 오류가 세션에 저장되어 뷰에서 표시할 수 있습니다. XHR 요청이라면 유효성 검사 오류가 담긴 JSON 응답이 422 상태 코드와 함께 반환됩니다.

NOTE

Inertia 기반 Laravel 프론트엔드에서 실시간 Form Request 유효성 검사를 추가하려면 Laravel Precognition을 살펴보세요.

추가 유효성 검사 수행

초기 검사가 완료된 후 추가 검사가 필요한 경우 Form Request의 after 메서드를 사용할 수 있습니다.

after 메서드는 검사 완료 후 호출될 콜러블 또는 클로저의 배열을 반환해야 합니다. 이 콜러블들은 Illuminate\Validation\Validator 인스턴스를 받아 필요한 경우 추가 오류 메시지를 등록할 수 있습니다.

use Illuminate\Validation\Validator;

/**
 * 요청에 대한 "after" 검사 콜러블 목록을 반환합니다.
 */
public function after(): array
{
    return [
        function (Validator $validator) {
            if ($this->somethingElseIsInvalid()) {
                $validator->errors()->add(
                    'field',
                    '이 필드에 문제가 있습니다!'
                );
            }
        }
    ];
}

after 메서드가 반환하는 배열에는 인보커블 클래스도 포함할 수 있습니다. 해당 클래스의 __invoke 메서드가 Illuminate\Validation\Validator 인스턴스를 받습니다.

use App\Validation\ValidateShippingTime;
use App\Validation\ValidateUserStatus;
use Illuminate\Validation\Validator;

/**
 * 요청에 대한 "after" 검사 콜러블 목록을 반환합니다.
 */
public function after(): array
{
    return [
        new ValidateUserStatus,
        new ValidateShippingTime,
        function (Validator $validator) {
            //
        }
    ];
}

첫 번째 실패 시 전체 검사 중단

Form Request 클래스에 stopOnFirstFailure 속성을 추가하면 하나의 필드에서 검사 실패가 발생하는 즉시 모든 필드의 검사를 중단합니다.

/**
 * 첫 번째 규칙 실패 시 검사를 중단할지 여부.
 *
 * @var bool
 */
protected $stopOnFirstFailure = true;

리다이렉트 위치 커스터마이징

Form Request 검사 실패 시 기본적으로 이전 위치로 리다이렉트됩니다. $redirect 속성을 정의하면 이 동작을 변경할 수 있습니다.

/**
 * 검사 실패 시 리다이렉트할 URI.
 *
 * @var string
 */
protected $redirect = '/dashboard';

이름 있는 라우트로 리다이렉트하려면 $redirectRoute 속성을 사용하세요.

/**
 * 검사 실패 시 리다이렉트할 라우트 이름.
 *
 * @var string
 */
protected $redirectRoute = 'dashboard';

Form Request 권한 검사

Form Request 클래스에는 authorize 메서드도 있습니다. 이 메서드에서 인증된 사용자가 해당 리소스를 수정할 권한이 있는지 확인합니다. 주로 인증 게이트와 정책과 연동하여 사용합니다.

use App\Models\Comment;

/**
 * 사용자가 이 요청을 수행할 권한이 있는지 확인합니다.
 */
public function authorize(): bool
{
    $comment = Comment::find($this->route('comment'));

    return $comment && $this->user()->can('update', $comment);
}

모든 Form Request는 기본 Laravel 요청 클래스를 상속하므로 user 메서드로 현재 인증된 사용자에 접근할 수 있습니다. 위 예시의 route 메서드는 {comment} 같이 라우트에 정의된 URI 파라미터에 접근할 수 있게 해줍니다.

Route::post('/comment/{comment}');

라우트 모델 바인딩을 활용하면 더 간결하게 작성할 수 있습니다.

return $this->user()->can('update', $this->comment);

authorize 메서드가 false를 반환하면 403 HTTP 응답이 자동으로 반환되고, 컨트롤러 메서드는 실행되지 않습니다.

애플리케이션의 다른 부분에서 권한 로직을 처리하는 경우 authorize 메서드를 제거하거나 단순히 true를 반환하면 됩니다.

/**
 * 사용자가 이 요청을 수행할 권한이 있는지 확인합니다.
 */
public function authorize(): bool
{
    return true;
}

NOTE

authorize 메서드 시그니처에도 의존성을 타입힌트로 선언할 수 있으며, Laravel 서비스 컨테이너가 자동으로 해결해 줍니다.

오류 메시지 커스터마이징

messages 메서드를 오버라이드하여 Form Request에서 사용할 오류 메시지를 커스터마이징할 수 있습니다. 이 메서드는 속성.규칙 => 메시지 형태의 배열을 반환해야 합니다.

/**
 * 정의된 유효성 검사 규칙에 대한 오류 메시지를 반환합니다.
 *
 * @return array<string, string>
 */
public function messages(): array
{
    return [
        'title.required' => '제목을 입력해 주세요.',
        'body.required' => '본문을 입력해 주세요.',
    ];
}

유효성 검사 속성명 커스터마이징

Laravel의 많은 내장 오류 메시지에는 :attribute 플레이스홀더가 포함되어 있습니다. 이 플레이스홀더를 커스텀 속성명으로 대체하려면 attributes 메서드를 오버라이드하세요.

/**
 * 유효성 검사 오류에 사용할 커스텀 속성명을 반환합니다.
 *
 * @return array<string, string>
 */
public function attributes(): array
{
    return [
        'email' => '이메일 주소',
    ];
}