유효성 검사

번역일: 2026년 6월 25일

유효성 검사

소개
빠른 시작
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(Ajax) 요청의 경우에는 유효성 검사 오류 메시지가 담긴 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은 사용자를 이전 페이지로 자동 리다이렉트합니다. 모든 유효성 검사 오류와 이전 요청 입력값은 자동으로 세션에 플래시됩니다.

$errors 변수는 web 미들웨어 그룹에 포함된 Illuminate\View\Middleware\ShareErrorsFromSession 미들웨어에 의해 모든 뷰에 자동으로 공유됩니다. 이 미들웨어가 적용되면 $errors 변수는 항상 사용 가능한 상태가 됩니다. $errors 변수는 Illuminate\Support\MessageBag 인스턴스입니다. 자세한 사용법은 오류 메시지 활용 섹션을 참고하세요.

아래와 같이 뷰에서 오류 메시지를 표시할 수 있습니다:

<!-- /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 명령어로 생성할 수 있습니다.

한국어 메시지를 사용하려면 lang/ko/validation.php 파일을 만들어 메시지를 번역하면 됩니다. Laravel 로컬라이제이션에 대한 자세한 내용은 로컬라이제이션 문서를 참고하세요.

WARNING

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

XHR 요청과 유효성 검사

XHR 요청(예: Axios, Fetch 등을 사용하는 프론트엔드)에서 validate 메서드를 호출하면 리다이렉트 대신 422 HTTP 상태 코드와 함께 유효성 검사 오류 메시지가 담긴 JSON 응답이 반환됩니다.

`@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

이름이 있는 오류 백을 사용하는 경우, @error 디렉티브의 두 번째 인수로 오류 백 이름을 전달합니다:

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

폼 값 다시 채우기

유효성 검사 실패로 리다이렉트가 발생하면, Laravel은 요청의 모든 입력값을 세션에 자동으로 플래시합니다. 다음 요청에서 old 메서드를 사용해 이전 입력값을 가져올 수 있습니다:

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

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

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

선택적 필드에 대한 참고사항

Laravel은 기본적으로 TrimStrings와 ConvertEmptyStringsToNull 미들웨어를 전역 미들웨어 스택에 포함하고 있습니다. 이 때문에 null 값을 허용하는 선택적 필드에는 nullable 규칙을 명시해야 합니다. 그렇지 않으면 유효성 검사기가 null을 유효하지 않은 값으로 처리합니다:

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

위 예에서 publish_at 필드는 null이거나 유효한 날짜 형식이어야 합니다.

유효성 검사 오류 응답 형식

Illuminate\Validation\ValidationException이 발생하고 클라이언트가 JSON 응답을 기대하는 경우, Laravel은 오류 메시지를 자동으로 포맷하여 422 Unprocessable Entity HTTP 응답을 반환합니다.

중첩된 오류 키는 "점" 표기법으로 평탄화됩니다:

{
    "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 명령어로 생성합니다:

php artisan make:request StorePostRequest

생성된 클래스는 app/Http/Requests 디렉터리에 위치하며, authorize와 rules 두 가지 메서드를 포함합니다.

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

/**
 * 요청에 적용할 유효성 검사 규칙을 반환합니다.
 *
 * @return array<string, \Illuminate\Contracts\Validation\Rule|array|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');
}

유효성 검사 실패 시 이전 URL로 리다이렉트되고 오류가 세션에 플래시됩니다. XHR 요청의 경우 422 상태 코드와 함께 JSON 오류 응답이 반환됩니다.

NOTE

Inertia 기반 Laravel 프론트엔드에서 실시간 유효성 검사가 필요하다면 Laravel Precognition을 확인하세요.

추가 유효성 검사 수행

초기 유효성 검사가 완료된 후 추가 검사가 필요한 경우 Form Request의 after 메서드를 사용합니다. 이 메서드는 유효성 검사 완료 후 호출될 클로저 또는 호출 가능한 배열을 반환해야 하며, 각 콜러블은 Illuminate\Validation\Validator 인스턴스를 전달받습니다:

use Illuminate\Validation\Validator;

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

after 메서드의 반환 배열에는 인보커블 클래스도 포함할 수 있습니다:

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

public function after(): array
{
    return [
        new ValidateUserStatus,
        new ValidateShippingTime,
        function (Validator $validator) {
            //
        }
    ];
}

첫 번째 유효성 검사 실패 시 중단

Form Request 클래스에 stopOnFirstFailure 프로퍼티를 추가하면 하나의 유효성 검사 실패 시 모든 속성의 검사를 중단합니다:

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

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

유효성 검사 실패 시 기본적으로 이전 URL로 리다이렉트되지만, $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 메서드로 라우트의 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 서비스 컨테이너가 자동으로 해결합니다.

오류 메시지 커스터마이징

Form Request에서 messages 메서드를 오버라이드하여 오류 메시지를 커스터마이징할 수 있습니다. 이 메서드는 속성/규칙 쌍과 해당 오류 메시지의 배열을 반환해야 합니다:

/**
 * 유효성 검사 규칙에 대한 오류 메시지를 반환합니다.
 *
 * @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' => '이메일 주소',
    ];
}

유효성 검사 전 입력 데이터 준비

유효성 검사 규칙을 적용하기 전에 요청 데이터를 정제하거나 변환해야 하는 경우 prepareForValidation 메서드를 사용합니다:

use Illuminate\Support\Str;

/**
 * 유효성 검사 전 데이터를 준비합니다.
 */
protected function prepareForValidation(): void
{
    $this->merge([
        'slug' => Str::slug($this->slug),
    ]);
}

유효성 검사가 완료된 후 데이터를 정규화해야 한다면 passedValidation 메서드를 사용합니다:

/**
 * 유효성 검사 통과 후 처리합니다.
 */
protected function passedValidation(): void
{
    $this->replace(['name' => 'Taylor']);
}

수동으로 Validator 생성

요청 객체의 validate 메서드 대신 Validator 파사드를 사용해 직접 Validator 인스턴스를 생성할 수도 있습니다:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class PostController extends Controller
{
    /**
     * 새 게시글을 저장합니다.