表單驗證 - Validation

• 簡介

• 「表單驗證」快速入門

  • Defining the Routes
  • Creating the Controller
  • Writing the Validation Logic
  • Displaying the Validation Errors
  • 重新回填表單
  • A Note on Optional Fields
  • 驗證錯誤的 Response 格式

• Form Request 的驗證

  • 建立 Form Request
  • 授權 Form Request
  • Customizing the Error Messages
  • Preparing Input for Validation

• 手動建立 Validator

  • 自動重新導向
  • 命名的 Error Bag
  • Customizing the Error Messages
  • Performing Additional Validation

• 處理已驗證的輸入

• 處理錯誤訊息

  • Specifying Custom Messages in Language Files
  • Specifying Attributes in Language Files
  • Specifying Values in Language Files

• 可用的表單驗證規則

• 條件式新增規則

• 驗證陣列

  • 驗證巢狀陣列輸入
  • Error Message Indexes and Positions

• 驗證

• 驗證密碼

• 自訂驗證規則

  • 使用 Rule 物件
  • 使用閉包
  • 隱式規則

簡介

Laravel 中提供了多種不同方式能讓我們對連入資料做驗證 (Validate)。最常見的方法就是使用所有連入 HTTP Request 上都有的 validata 方法來驗證。不過，我們稍後也會討論其他驗證方法。

Laravel 中包含了多種方便的驗證規則可讓你套用到資料上，甚至，Laravel 中也有辦法驗證某個值在給定資料表上是否是不重複的。稍後我們會詳細說明各個驗證規則，讓你熟悉 Laravel 中所有的驗證功能。

「Validation」快速開始

要瞭解有關 Laravel 中強大的驗證功能，我們先來看看一個驗證表單並將錯誤訊息顯示給使用者看的完整範例。閱讀這個高階的範例，讀者將能對如何使用 Laravel 驗證連入的 Request 資料有個基本的理解：

Defining the Routes

首先，我們假設 routes/web.php 檔案中有下列 Route 定義：

1use App\Http\Controllers\PostController;
2 
3Route::get('/post/create', [PostController::class, 'create']);
4Route::post('/post', [PostController::class, 'store']);
1use App\Http\Controllers\PostController;
2 
3Route::get('/post/create', [PostController::class, 'create']);
4Route::post('/post', [PostController::class, 'store']);

這個 GET Route 會向使用者顯示一個用來建立新部落格貼文的表單，而 POST Route 則用來將新部落格貼文儲存到資料庫中。

Creating the Controller

接著，我們來看看一個簡單的 Controller，這個 Controller 用來處理這些 Route 的連入 Request。我們現在先把 store 方法留空：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\RedirectResponse;
 6use Illuminate\Http\Request;
 7use Illuminate\View\View;
 8 
 9class PostController extends Controller
10{
11    /**
12     * Show the form to create a new blog post.
13     */
14    public function create(): View
15    {
16        return view('post.create');
17    }
18 
19    /**
20     * Store a new blog post.
21     */
22    public function store(Request $request): RedirectResponse
23    {
24        // Validate and store the blog post...
25 
26        $post = /** ... */
27 
28        return to_route('post.show', ['post' => $post->id]);
29    }
30}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\RedirectResponse;
 6use Illuminate\Http\Request;
 7use Illuminate\View\View;
 8 
 9class PostController extends Controller
10{
11    /**
12     * Show the form to create a new blog post.
13     */
14    public function create(): View
15    {
16        return view('post.create');
17    }
18 
19    /**
20     * Store a new blog post.
21     */
22    public function store(Request $request): RedirectResponse
23    {
24        // Validate and store the blog post...
25 
26        $post = /** ... */
27 
28        return to_route('post.show', ['post' => $post->id]);
29    }
30}

Writing the Validation Logic

現在，我們已經準備好可以在 store 方法內撰寫驗證新部落格貼文的驗證邏輯了。要撰寫驗證邏輯，我們會使用 Illuminate\Http\Request 物件所提供的 validate 方法。若驗證規則通過，則程式碼就可以繼續正常執行。不過，若驗證失敗，則會擲回 Illuminate\Validation\ValidationException 例外，然後 Laravel 會自動回傳適當的錯誤 Response 給使用者。

若驗證失敗時使用的是傳統 HTTP Request，則會產生一個回到上一頁網址的 Redirect Response。若連入的 Request 是 XHR Request，則會回傳一個[包含驗證錯誤訊息的 JSON Response]](#validation-error-response-format)。

為了更好瞭解 validate，我們先回來看看 store 方法：

 1/**
 2 * Store a new blog post.
 3 */
 4public function store(Request $request): RedirectResponse
 5{
 6    $validated = $request->validate([
 7        'title' => 'required|unique:posts|max:255',
 8        'body' => 'required',
 9    ]);
10 
11    // The blog post is valid...
12 
13    return redirect('/posts');
14}
 1/**
 2 * Store a new blog post.
 3 */
 4public function store(Request $request): RedirectResponse
 5{
 6    $validated = $request->validate([
 7        'title' => 'required|unique:posts|max:255',
 8        'body' => 'required',
 9    ]);
10 
11    // The blog post is valid...
12 
13    return redirect('/posts');
14}

就像我們可以看到的一樣，我們將驗證規則傳入 validate 方法。別擔心 —— 所有可用的規則都有說明文件。一樣，若驗證失敗，會自動產生適當的 Response。若驗證成功，我們的 Controller 就會繼續正常執行。

或者，我們也可以不使用以 | 分隔的單一字串來指定驗證規則，而是使用一組規則陣列：

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

此外，也可以使用 validateWithBag 方法來驗證 Request 並將錯誤訊息保存在一個命名的 Error Bag：

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

Stopping on First Validation Failure

有時候，我們會想在驗證某個屬性時，當遇到第一個驗證失敗就停止執行接下來的驗證規則。為此，可以在該屬性上加上 bail 規則：

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

在這個例子中，若 title 屬性上的 unique 規則執行失敗，將不會檢查 max 規則。會依照所指派的順序來執行驗證規則。

A Note on Nested Attributes

若連入的 HTTP Request 中包含「巢狀」的欄位資料，請使用「點 (.)」語法來在驗證規則中指定這些欄位：

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

另一方面，若欄位名稱包含 . 字元，則我們可以使用反斜線來逸出句點，以顯式避免被解析成「點 (.)」語法：

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

Displaying the Validation Errors

那麼，如果連入 Request 的欄位沒通過給定的驗證規則呢？就像剛才提到過的，Laravel 會自動將使用者重新導向回到上一個位置。此外，所有的驗證規則與 Request 輸入都會自動被快閃存入 Session。

Illuminate\View\Middleware\ShareErrorsFromSession Middleware 幫我們在專案中所有的 View 間共享了一個 $errors 變數。這個 Middleware 在 web Middleware 群組中提供。當有套用這個 Middleware 時，所有的 View 中都會有 $errors 變數，因此我們能方便地假設 $errors 變數擁有都已定義好且可安全地使用。$errors 變數是 Illuminate\Support\MessageBag 的實體。更多有關該物件的資訊，請參考 Message Bag 的說明文件。

所有，在我們的範例中，當驗證失敗時，使用者會被重新導向到 Controller 的 create 方法，讓我們能在 View 中顯示錯誤訊息：

 1<!-- /resources/views/post/create.blade.php -->
 2 
 3<h1>Create Post</h1>
 4 
 5@if ($errors->any())
 6    <div class="alert alert-danger">
 7        <ul>
 8            @foreach ($errors->all() as $error)
 9                <li>{{ $error }}</li>
10            @endforeach
11        </ul>
12    </div>
13@endif
14 
15<!-- Create Post Form -->
 1<!-- /resources/views/post/create.blade.php -->
 2 
 3<h1>Create Post</h1>
 4 
 5@if ($errors->any())
 6    <div class="alert alert-danger">
 7        <ul>
 8            @foreach ($errors->all() as $error)
 9                <li>{{ $error }}</li>
10            @endforeach
11        </ul>
12    </div>
13@endif
14 
15<!-- Create Post Form -->

Customizing the Error Messages

Laravel's built-in validation rules each have an error message that is located in your application's lang/en/validation.php file. If your application does not have a lang directory, you may instruct Laravel to create it using the lang:publish Artisan command.

Within the lang/en/validation.php file, you will find a translation entry for each validation rule. You are free to change or modify these messages based on the needs of your application.

此外，也可以把這個檔案複製到另一個翻譯語系目錄中，以將其翻成你專案的語言。要瞭解 Laravel 中有關本土化 (Localization) 的更多資訊，請參考完整的本土化說明文件。

XHR Requests and Validation

在這個例子中，我們使用傳統的表單來將資料傳給程式。不過，有許多程式是接受來自 JavaScript 前端的 XHR Request。在 XHR Request 中使用 validate 方法時，Laravel 不會產生 Redirect Response，而是產生一個包含所有驗證錯誤的 JSON Response。JSON Response 會以 422 HTTP 狀態碼傳送。

@error 指示詞

可以使用 @error Blade 指示詞來快速判斷給定的屬性是否有驗證錯誤訊息。在 @error 指示詞內，可以輸出 $message 變數來顯示錯誤訊息：

 1<!-- /resources/views/post/create.blade.php -->
 2 
 3<label for="title">Post Title</label>
 4 
 5<input id="title"
 6    type="text"
 7    name="title"
 8    class="@error('title') is-invalid @enderror">
 9 
10@error('title')
11    <div class="alert alert-danger">{{ $message }}</div>
12@enderror
 1<!-- /resources/views/post/create.blade.php -->
 2 
 3<label for="title">Post Title</label>
 4 
 5<input id="title"
 6    type="text"
 7    name="title"
 8    class="@error('title') is-invalid @enderror">
 9 
10@error('title')
11    <div class="alert alert-danger">{{ $message }}</div>
12@enderror

若使用命名的 Error Bag，則可將 Error Bag 的名稱作為第二個引數傳給 @error 指示詞：

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

重新回填表單

當 Laravel 因為驗證錯誤而產生 Redirect Response 時，Laravel 會自動將目前的 Request 輸入快閃存入 Session。這樣一來我們就能在下一個 Request 中方便地存取這些輸入，並將資料重新回填到使用者嘗試送出的表單上。

若要取得前一個 Request 中的快閃輸入，可叫用 Illuminate\Http\Request 上的 old 方法。old 方法從 Session 中拉取前次快閃存入輸入資料：

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

Laravel 也提供了一個全域 old 輔助函式。若想在 Blade 樣板中顯示舊輸入，那麼使用 old 輔助函式來將其填回表單回比較方便。若給定欄位沒有舊輸入的話，會回傳 null：

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

A Note on Optional Fields

預設情況下，Laravel 的全域 Middleware Stack 中包含了 TrimStrings 與 ConvertEmptyStringsToNull Middleware。這兩個 Middleware 由 App\Http\Kernel 類別列在一個 Stack 中。因此，如果不希望 Validator (驗證程式) 把 null 值當作無效資料的話，我們常常需要將「可選填」的 Request 欄位標為 nullable。舉例來說：

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

在這個範例中，我們指定讓 publish_at 欄位可以是 null 或是有效的日期呈現。若沒有在規則定義中加上 nullabale 修飾詞 (Modifier)，則 Validator 會把 null 當作無效的日期。

驗證錯誤的 Response 格式

當專案擲回 Illuminate\Validation\ValidationException Exception 且連入 HTTP Request 預期要回傳 JSON Response 時，Laravel 會自動格式化錯誤訊息，並回傳 422 Unprocessable Entity HTTP Response。

下方是一個範例的驗證錯誤 JSON Response 格式。請注意，巢狀的錯誤索引鍵會被扁平化為「點 (.)」表示法：

 1{
 2    "message": "The team name must be a string. (and 4 more errors)",
 3    "errors": {
 4        "team_name": [
 5            "The team name must be a string.",
 6            "The team name must be at least 1 characters."
 7        ],
 8        "authorization.role": [
 9            "The selected authorization.role is invalid."
10        ],
11        "users.0.email": [
12            "The users.0.email field is required."
13        ],
14        "users.2.email": [
15            "The users.2.email must be a valid email address."
16        ]
17    }
18}
 1{
 2    "message": "The team name must be a string. (and 4 more errors)",
 3    "errors": {
 4        "team_name": [
 5            "The team name must be a string.",
 6            "The team name must be at least 1 characters."
 7        ],
 8        "authorization.role": [
 9            "The selected authorization.role is invalid."
10        ],
11        "users.0.email": [
12            "The users.0.email field is required."
13        ],
14        "users.2.email": [
15            "The users.2.email must be a valid email address."
16        ]
17    }
18}

Form Request 的驗證

建立 Form Request

在更複雜的驗證情境中，我們可能會想建立一個「Form Request (表單請求)」。Form Request 就是自訂的 Request 類別，其中封裝了該 Request 自己的驗證與認證邏輯。若要建立 Form Request 類別，可使用 make:request Artisan CLI 指令：

1php artisan make:request StorePostRequest
1php artisan make:request StorePostRequest

產生的 Form Request 會被放在 app/Http/Requests 目錄中。若該目錄不存在，則執行 make:request 指令是會自動建立。Laravel 產生的每個 Form Request 都有兩個方法：authorize 與 rules。

讀者可能已經猜到，authorize 方法是用來判斷目前已登入使用者是否能進行該 Request 所代表的動作。rules 方法則回傳要套用到 Request 資料的驗證規則：

 1/**
 2 * Get the validation rules that apply to the request.
 3 *
 4 * @return array<string, \Illuminate\Contracts\Validation\Rule|array|string>
 5 */
 6public function rules(): array
 7{
 8    return [
 9        'title' => 'required|unique:posts|max:255',
10        'body' => 'required',
11    ];
12}
 1/**
 2 * Get the validation rules that apply to the request.
 3 *
 4 * @return array<string, \Illuminate\Contracts\Validation\Rule|array|string>
 5 */
 6public function rules(): array
 7{
 8    return [
 9        'title' => 'required|unique:posts|max:255',
10        'body' => 'required',
11    ];
12}

那麼，要怎麼執行驗證規則呢？我們只需要在 Controller 方法中型別提示這個 Request 即可。連入的 Form Request 會在呼叫 Controller 方法前驗證。這表示，我們就不需要在 Controller 中放一些凌亂的驗證邏輯：

 1/**
 2 * Store a new blog post.
 3 */
 4public function store(StorePostRequest $request): RedirectResponse
 5{
 6    // The incoming request is valid...
 7 
 8    // Retrieve the validated input data...
 9    $validated = $request->validated();
10 
11    // Retrieve a portion of the validated input data...
12    $validated = $request->safe()->only(['name', 'email']);
13    $validated = $request->safe()->except(['name', 'email']);
14 
15    // Store the blog post...
16 
17    return redirect('/posts');
18}
 1/**
 2 * Store a new blog post.
 3 */
 4public function store(StorePostRequest $request): RedirectResponse
 5{
 6    // The incoming request is valid...
 7 
 8    // Retrieve the validated input data...
 9    $validated = $request->validated();
10 
11    // Retrieve a portion of the validated input data...
12    $validated = $request->safe()->only(['name', 'email']);
13    $validated = $request->safe()->except(['name', 'email']);
14 
15    // Store the blog post...
16 
17    return redirect('/posts');
18}

若驗證失敗，會產生一個 Redirect Response，並將使用者傳送回前一個位置。錯誤訊息也會被快閃存入 Session 中以便顯示。若目前的 Request 是 XHR Request，則會回傳一個 422 狀態碼的 HTTP Response 給使用者，其中包含了以 JSON 呈現的驗證錯誤訊息：

Performing Additional Validation

Sometimes you need to perform additional validation after your initial validation is complete. You can accomplish this using the form request's after method.

The after method should return an array of callables or closures which will be invoked after validation is complete. The given callables will receive an Illuminate\Validation\Validator instance, allowing you to raise additional error messages if necessary:

 1use Illuminate\Validation\Validator;
 2 
 3/**
 4 * Get the "after" validation callables for the request.
 5 */
 6public function after(): array
 7{
 8    return [
 9        function (Validator $validator) {
10            if ($this->somethingElseIsInvalid()) {
11                $validator->errors()->add(
12                    'field',
13                    'Something is wrong with this field!'
14                );
15            }
16        }
17    ];
18}
 1use Illuminate\Validation\Validator;
 2 
 3/**
 4 * Get the "after" validation callables for the request.
 5 */
 6public function after(): array
 7{
 8    return [
 9        function (Validator $validator) {
10            if ($this->somethingElseIsInvalid()) {
11                $validator->errors()->add(
12                    'field',
13                    'Something is wrong with this field!'
14                );
15            }
16        }
17    ];
18}

As noted, the array returned by the after method may also contain invokable classes. The __invoke method of these classes will receive an Illuminate\Validation\Validator instance:

 1use App\Validation\ValidateShippingTime;
 2use App\Validation\ValidateUserStatus;
 3use Illuminate\Validation\Validator;
 4 
 5/**
 6 * Get the "after" validation callables for the request.
 7 */
 8public function after(): array
 9{
10    return [
11        new ValidateUserStatus,
12        new ValidateShippingTime,
13        function (Validator $validator) {
14            //
15        }
16    ];
17}
 1use App\Validation\ValidateShippingTime;
 2use App\Validation\ValidateUserStatus;
 3use Illuminate\Validation\Validator;
 4 
 5/**
 6 * Get the "after" validation callables for the request.
 7 */
 8public function after(): array
 9{
10    return [
11        new ValidateUserStatus,
12        new ValidateShippingTime,
13        function (Validator $validator) {
14            //
15        }
16    ];
17}

Stopping on the First Validation Failure

在 Request 類別上新增 stopOnFirstFailure 屬性後，就可以讓 Validator 在發生一個驗證失敗後就停止驗證所有的屬性：

1/**
2 * Indicates if the validator should stop on the first rule failure.
3 *
4 * @var bool
5 */
6protected $stopOnFirstFailure = true;
1/**
2 * Indicates if the validator should stop on the first rule failure.
3 *
4 * @var bool
5 */
6protected $stopOnFirstFailure = true;

Customizing the Redirect Location

前面也提到過，Form Request 驗證失敗時會產生一個 Redirect Response 來將使用者傳送到前一個位置。不過，我們可以自訂這個行為。為此，請在 Form Request 中定義一個 $redirect 屬性：

1/**
2 * The URI that users should be redirected to if validation fails.
3 *
4 * @var string
5 */
6protected $redirect = '/dashboard';
1/**
2 * The URI that users should be redirected to if validation fails.
3 *
4 * @var string
5 */
6protected $redirect = '/dashboard';

或者，若想將使用者重新導向到命名 Route，請改定義 $redirectRoute 屬性：

1/**
2 * The route that users should be redirected to if validation fails.
3 *
4 * @var string
5 */
6protected $redirectRoute = 'dashboard';
1/**
2 * The route that users should be redirected to if validation fails.
3 *
4 * @var string
5 */
6protected $redirectRoute = 'dashboard';

授權 Form Request

Form Request 類別中也包含了一個 authorize 方法。在這個方法中，我們可以判斷已登入使用者是否有授權能更新給定資源。舉例來說，我們可以判斷使用者是否真的擁有正在編輯的部落格留言。大多數情況下，在這個方法中我們應該都是使用授權的 Gate 與 Policy：

 1use App\Models\Comment;
 2 
 3/**
 4 * Determine if the user is authorized to make this request.
 5 */
 6public function authorize(): bool
 7{
 8    $comment = Comment::find($this->route('comment'));
 9 
10    return $comment && $this->user()->can('update', $comment);
11}
 1use App\Models\Comment;
 2 
 3/**
 4 * Determine if the user is authorized to make this request.
 5 */
 6public function authorize(): bool
 7{
 8    $comment = Comment::find($this->route('comment'));
 9 
10    return $comment && $this->user()->can('update', $comment);
11}

由於所有 Form Request 都繼承自 Laravel 的基礎 Request 類別，因此我們可以使用 user 方法來存取目前已登入的使用者。此外，也請注意上方範例中呼叫的 route 方法。這個方法能讓我們存取目前呼叫的 Route 上的 URI 參數，如上述例子中為 {comment} 參數：

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

因此，若我們的專案有使用 Route Model 繫結，則這裡的程式碼還能存取 Request 上已解析的 Model 屬性來進一步簡化：

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

若 authorize 方法回傳 false，則會自動回傳一個 403 狀態碼的 HTTP Respnose，而 Controller 則不會被執行。

If you plan to handle authorization logic for the request in another part of your application, you may remove the authorize method completely, or simply return true:

1/**
2 * Determine if the user is authorized to make this request.
3 */
4public function authorize(): bool
5{
6    return true;
7}
1/**
2 * Determine if the user is authorized to make this request.
3 */
4public function authorize(): bool
5{
6    return true;
7}

Customizing the Error Messages

可以複寫 messages 方法來自訂 Form Request 使用的錯誤訊息。這個方法應回傳一組包含屬性/ 規則配對的陣列與其對應的錯誤訊息：

 1/**
 2 * Get the error messages for the defined validation rules.
 3 *
 4 * @return array<string, string>
 5 */
 6public function messages(): array
 7{
 8    return [
 9        'title.required' => 'A title is required',
10        'body.required' => 'A message is required',
11    ];
12}
 1/**
 2 * Get the error messages for the defined validation rules.
 3 *
 4 * @return array<string, string>
 5 */
 6public function messages(): array
 7{
 8    return [
 9        'title.required' => 'A title is required',
10        'body.required' => 'A message is required',
11    ];
12}

Customizing the Validation Attributes

Laravel 中許多的內建驗證規則錯誤訊息都包含了一個 :attribute 預留位置 (Placeholder)。若想將驗證訊息中 :attribute 預留位置該為自訂屬性名稱，可以複寫 attributes 方法來指定自訂的名稱。這個方法應回傳一組包含屬性 / 名稱配對的陣列：

 1/**
 2 * Get custom attributes for validator errors.
 3 *
 4 * @return array<string, string>
 5 */
 6public function attributes(): array
 7{
 8    return [
 9        'email' => 'email address',
10    ];
11}
 1/**
 2 * Get custom attributes for validator errors.
 3 *
 4 * @return array<string, string>
 5 */
 6public function attributes(): array
 7{
 8    return [
 9        'email' => 'email address',
10    ];
11}

Preparing Input for Validation

若有需要在套用驗證規則前準備或消毒 (Sanitize) 任何 Request 中的資料，可使用 prepareForValidation 方法：

 1use Illuminate\Support\Str;
 2 
 3/**
 4 * Prepare the data for validation.
 5 */
 6protected function prepareForValidation(): void
 7{
 8    $this->merge([
 9        'slug' => Str::slug($this->slug),
10    ]);
11}
 1use Illuminate\Support\Str;
 2 
 3/**
 4 * Prepare the data for validation.
 5 */
 6protected function prepareForValidation(): void
 7{
 8    $this->merge([
 9        'slug' => Str::slug($this->slug),
10    ]);
11}

類似地，若有需要在驗證完成後正常化任何 Request 資料，可使用 passedValidation 方法：

1/**
2 * Handle a passed validation attempt.
3 */
4protected function passedValidation(): void
5{
6    $this->replace(['name' => 'Taylor']);
7}
1/**
2 * Handle a passed validation attempt.
3 */
4protected function passedValidation(): void
5{
6    $this->replace(['name' => 'Taylor']);
7}

手動建立 Validator

若不想使用 Request 上的 validate 方法，也可以使用 Validator Facade 來手動建立 Validator 實體。Facade 方法上的 make 方法會產生新的 Validator 實體：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\RedirectResponse;
 6use Illuminate\Http\Request;
 7use Illuminate\Support\Facades\Validator;
 8 
 9class PostController extends Controller
10{
11    /**
12     * Store a new blog post.
13     */
14    public function store(Request $request): RedirectResponse
15    {
16        $validator = Validator::make($request->all(), [
17            'title' => 'required|unique:posts|max:255',
18            'body' => 'required',
19        ]);
20 
21        if ($validator->fails()) {
22            return redirect('post/create')
23                        ->withErrors($validator)
24                        ->withInput();
25        }
26 
27        // Retrieve the validated input...
28        $validated = $validator->validated();
29 
30        // Retrieve a portion of the validated input...
31        $validated = $validator->safe()->only(['name', 'email']);
32        $validated = $validator->safe()->except(['name', 'email']);
33 
34        // Store the blog post...
35 
36        return redirect('/posts');
37    }
38}
 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\RedirectResponse;
 6use Illuminate\Http\Request;
 7use Illuminate\Support\Facades\Validator;
 8 
 9class PostController extends Controller
10{
11    /**
12     * Store a new blog post.
13     */
14    public function store(Request $request): RedirectResponse
15    {
16        $validator = Validator::make($request->all(), [
17            'title' => 'required|unique:posts|max:255',
18            'body' => 'required',
19        ]);
20 
21        if ($validator->fails()) {
22            return redirect('post/create')
23                        ->withErrors($validator)
24                        ->withInput();
25        }
26 
27        // Retrieve the validated input...
28        $validated = $validator->validated();
29 
30        // Retrieve a portion of the validated input...
31        $validated = $validator->safe()->only(['name', 'email']);
32        $validated = $validator->safe()->except(['name', 'email']);
33 
34        // Store the blog post...
35 
36        return redirect('/posts');
37    }
38}

傳入 make 方法的第一個屬性是要驗證的資料。第二個引述則是一組要套用到給定資料上的驗證規則陣列。

在判斷 Request 是否驗證失敗後，可以使用 withErrors 方法來將錯誤訊息快閃存入 Session 中。使用這個方法時，重新導向後會自動共享 $errors 變數，讓我們能輕鬆將其顯示給使用者。withErrors 方法接受一個 Validator、MessageBag、或 PHP array。

Stopping on First Validation Failure

stopOnFirstFailure 方法可以讓 Validator 在發生一個驗證失敗後就停止驗證所有的屬性：

1if ($validator->stopOnFirstFailure()->fails()) {
2    // ...
3}
1if ($validator->stopOnFirstFailure()->fails()) {
2    // ...
3}

自動重新導向

若想手動建立 Validator 實體，但也想要使用 HTTP Request 的 validate 方法提供的自動重新導向功能，可以在現有 Validator 實體上呼叫 validate 方法。若驗證失敗，使用者會被重新導向。XHR Request 的情況下，則會回傳 JSON Response：

1Validator::make($request->all(), [
2    'title' => 'required|unique:posts|max:255',
3    'body' => 'required',
4])->validate();
1Validator::make($request->all(), [
2    'title' => 'required|unique:posts|max:255',
3    'body' => 'required',
4])->validate();

可以使用 validateWithBag 方法來在驗證失敗時將錯誤訊息保存在命名的 Error Bag 中：

1Validator::make($request->all(), [
2    'title' => 'required|unique:posts|max:255',
3    'body' => 'required',
4])->validateWithBag('post');
1Validator::make($request->all(), [
2    'title' => 'required|unique:posts|max:255',
3    'body' => 'required',
4])->validateWithBag('post');

命名的 Error Bag

若單一頁面中有多個表單，則我們可能會想為保存錯誤訊息的 MessageBag 命名。這樣一來，我們就可以為特定的表單取得錯誤訊息。為此，請傳入名稱作為第二個引數給 withErrors：

1return redirect('register')->withErrors($validator, 'login');
1return redirect('register')->withErrors($validator, 'login');

接著我們就可以在 $errors 變數中存取命名的 MessageBag 實體：

1{{ $errors->login->first('email') }}
1{{ $errors->login->first('email') }}

Customizing the Error Messages

當然，除了 Laravel 提供的預設錯誤訊息外，我們還可以提供自訂的錯誤訊息給 Validator 實體使用。有許多方法可以指定自訂訊息。第一個方法是，將自訂訊息作為第三個引數傳給 Validator::make 方法：

1$validator = Validator::make($input, $rules, $messages = [
2    'required' => 'The :attribute field is required.',
3]);
1$validator = Validator::make($input, $rules, $messages = [
2    'required' => 'The :attribute field is required.',
3]);

在這個例子中，:attribute 預留位置 (Placeholder) 會被替換成驗證中的實際欄位名稱。我們也可以在驗證訊息中使用其他的預留位置，如：

1$messages = [
2    'same' => 'The :attribute and :other must match.',
3    'size' => 'The :attribute must be exactly :size.',
4    'between' => 'The :attribute value :input is not between :min - :max.',
5    'in' => 'The :attribute must be one of the following types: :values',
6];
1$messages = [
2    'same' => 'The :attribute and :other must match.',
3    'size' => 'The :attribute must be exactly :size.',
4    'between' => 'The :attribute value :input is not between :min - :max.',
5    'in' => 'The :attribute must be one of the following types: :values',
6];

Specifying a Custom Message for a Given Attribute

有時候我們可能會想指為特定的屬性指定錯誤訊息。為此，我們可以使用「點 (.)」標記法。先指定屬性的名稱，然後再加上規則名稱：

1$messages = [
2    'email.required' => 'We need to know your email address!',
3];
1$messages = [
2    'email.required' => 'We need to know your email address!',
3];

指定自訂屬性值

Laravel 中許多內建的錯誤訊息都包含了一個 :attribute 預留位置，會被取代成正在驗證的欄位名稱或屬性名稱。若想在指定的欄位上自使用自訂值來取代這些預留位置，可將一組自訂屬性的陣列作為第四個引數傳給 Validator::make 方法：

1$validator = Validator::make($input, $rules, $messages, [
2    'email' => 'email address',
3]);
1$validator = Validator::make($input, $rules, $messages, [
2    'email' => 'email address',
3]);

Performing Additional Validation

Sometimes you need to perform additional validation after your initial validation is complete. You can accomplish this using the validator's after method. The after method accepts a closure or an array of callables which will be invoked after validation is complete. The given callables will receive an Illuminate\Validation\Validator instance, allowing you to raise additional error messages if necessary:

 1use Illuminate\Support\Facades\Validator;
 2 
 3$validator = Validator::make(/* ... */);
 4 
 5$validator->after(function ($validator) {
 6    if ($this->somethingElseIsInvalid()) {
 7        $validator->errors()->add(
 8            'field', 'Something is wrong with this field!'
 9        );
10    }
11});
12 
13if ($validator->fails()) {
14    // ...
15}
 1use Illuminate\Support\Facades\Validator;
 2 
 3$validator = Validator::make(/* ... */);
 4 
 5$validator->after(function ($validator) {
 6    if ($this->somethingElseIsInvalid()) {
 7        $validator->errors()->add(
 8            'field', 'Something is wrong with this field!'
 9        );
10    }
11});
12 
13if ($validator->fails()) {
14    // ...
15}

As noted, the after method also accepts an array of callables, which is particularly convenient if your "after validation" logic is encapsulated in invokable classes, which will receive an Illuminate\Validation\Validator instance via their __invoke method:

 1use App\Validation\ValidateShippingTime;
 2use App\Validation\ValidateUserStatus;
 3 
 4$validator->after([
 5    new ValidateUserStatus,
 6    new ValidateShippingTime,
 7    function ($validator) {
 8        // ...
 9    },
10]);
 1use App\Validation\ValidateShippingTime;
 2use App\Validation\ValidateUserStatus;
 3 
 4$validator->after([
 5    new ValidateUserStatus,
 6    new ValidateShippingTime,
 7    function ($validator) {
 8        // ...
 9    },
10]);

處理已驗證的輸入

使用 Form Request 或手動建立的 Validator 實體驗證好連入的 Request 資料後，我們可能會想取得連入 Request 中實際被驗證過的資料。有許多種方法可以取得這些資料。第一種方法是在 Form Request 或 Validator 實體上呼叫 validated 方法。這個方法會回傳一組驗證過的資料陣列：

1$validated = $request->validated();
2 
3$validated = $validator->validated();
1$validated = $request->validated();
2 
3$validated = $validator->validated();

或者，也可以在 Form Request 或 Validator 實體上呼叫 safe 方法。這個方法會回傳一個 Illuminate\Support\ValidatedInput 實體。該物件提供了 only、except、all 等方法，可用來取得一部分已驗證的資料或是整個已驗證資料的陣列：

1$validated = $request->safe()->only(['name', 'email']);
2 
3$validated = $request->safe()->except(['name', 'email']);
4 
5$validated = $request->safe()->all();
1$validated = $request->safe()->only(['name', 'email']);
2 
3$validated = $request->safe()->except(['name', 'email']);
4 
5$validated = $request->safe()->all();

此外，也可迭代 Illuminate\Support\ValidatedInput 或像陣列一樣存取：

1// Validated data may be iterated...
2foreach ($request->safe() as $key => $value) {
3    // ...
4}
5 
6// Validated data may be accessed as an array...
7$validated = $request->safe();
8 
9$email = $validated['email'];
1// Validated data may be iterated...
2foreach ($request->safe() as $key => $value) {
3    // ...
4}
5 
6// Validated data may be accessed as an array...
7$validated = $request->safe();
8 
9$email = $validated['email'];

若想在已驗證資料上加上額外的欄位，可呼叫 merge 方法：

1$validated = $request->safe()->merge(['name' => 'Taylor Otwell']);
1$validated = $request->safe()->merge(['name' => 'Taylor Otwell']);

若想將已驗證資料作為 Collection 實體取得，可呼叫 collect 方法：

1$collection = $request->safe()->collect();
1$collection = $request->safe()->collect();

處理錯誤訊息

在 Validator 實體上呼叫 errors 方法後，會收到 Illuminate\Support\MessageBag 實體。該實體提供了多種方便的方法能讓我們處理錯誤訊息。自動提供給所有 View 的 $errors 變數也是一個 MessageBag 類別的實體。

Retrieving the First Error Message for a Field

若要取得給定欄位的第一筆錯誤訊息，請使用 first 方法：

1$errors = $validator->errors();
2 
3echo $errors->first('email');
1$errors = $validator->errors();
2 
3echo $errors->first('email');

Retrieving All Error Messages for a Field

若需要取得給定欄位的所有訊息陣列，請使用 get 方法：

1foreach ($errors->get('email') as $message) {
2    // ...
3}
1foreach ($errors->get('email') as $message) {
2    // ...
3}

在驗證某個陣列格式的表單欄位時，可使用 * 字元來取得各個陣列元素的所有錯誤訊息：

1foreach ($errors->get('attachments.*') as $message) {
2    // ...
3}
1foreach ($errors->get('attachments.*') as $message) {
2    // ...
3}

Retrieving All Error Messages for All Fields

若要取得所有欄位的所有訊息陣列，請使用 all 方法：

1foreach ($errors->all() as $message) {
2    // ...
3}
1foreach ($errors->all() as $message) {
2    // ...
3}

Determining if Messages Exist for a Field

has 方法可用來判斷給定的欄位是否有錯誤訊息：

1if ($errors->has('email')) {
2    // ...
3}
1if ($errors->has('email')) {
2    // ...
3}

Specifying Custom Messages in Language Files

Laravel's built-in validation rules each have an error message that is located in your application's lang/en/validation.php file. If your application does not have a lang directory, you may instruct Laravel to create it using the lang:publish Artisan command.

Within the lang/en/validation.php file, you will find a translation entry for each validation rule. You are free to change or modify these messages based on the needs of your application.

此外，也可以把這個檔案複製到另一個翻譯語系目錄中，以將其翻成你專案的語言。要瞭解 Laravel 中有關本土化 (Localization) 的更多資訊，請參考完整的本土化說明文件。

Custom Messages for Specific Attributes

我們可能會想在程式的驗證語系檔中為特定的屬性與規則組合自訂錯誤訊息。為此，請在專案的 lang/xx/validation.php 語系檔中 custom 陣列內新增你的自訂訊息：

1'custom' => [
2    'email' => [
3        'required' => 'We need to know your email address!',
4        'max' => 'Your email address is too long!'
5    ],
6],
1'custom' => [
2    'email' => [
3        'required' => 'We need to know your email address!',
4        'max' => 'Your email address is too long!'
5    ],
6],

Specifying Attributes in Language Files

Laravel 中內建的許多錯誤訊息都包含了一個 :attribute 預留位置 (Placeholder)，該預留位置會被取代為被驗證的欄位名稱或屬性名稱。若想讓驗證訊息的 :attribute 部分被取代為自訂的值，可在 lang/xx/validation.php 語系檔中 attributes 陣列內指定自訂的屬性名稱：

1'attributes' => [
2    'email' => 'email address',
3],
1'attributes' => [
2    'email' => 'email address',
3],

Specifying Values in Language Files

Laravel 中有些內建的驗證規則錯誤訊息中包含了一個 :value 預留位置 (Placeholder)，這個預留位置會被取代為目前 Request 中的屬性值。不過，有時候我們會像讓驗證訊息中的 :value 部分被取代為用於該值的自訂呈現方式。舉例來說，假設我們套用了下列規則來讓 payment_type 值為 cc 時，信用卡卡號為必填：

1Validator::make($request->all(), [
2    'credit_card_number' => 'required_if:payment_type,cc'
3]);
1Validator::make($request->all(), [
2    'credit_card_number' => 'required_if:payment_type,cc'
3]);

若驗證規則執行失敗，會產生下列錯誤訊息：

1The credit card number field is required when payment type is cc.
1The credit card number field is required when payment type is cc.

我們可以在 lang/xx/validation.php 語系檔中定義一個 values 陣列來為付款方式的值指定一個對使用者更友好的呈現，而不是顯示 cc：

1'values' => [
2    'payment_type' => [
3        'cc' => 'credit card'
4    ],
5],
1'values' => [
2    'payment_type' => [
3        'cc' => 'credit card'
4    ],
5],

定義好這個值之後，剛才的驗證規則會產生下列錯誤訊息：

1The credit card number field is required when payment type is credit card.
1The credit card number field is required when payment type is credit card.

可用的驗證規則

下面列出了所有可用的驗證規則與其函式：

accepted

The field under validation must be "yes", "on", 1, "1", true, or "true". This is useful for validating "Terms of Service" acceptance or similar fields.

accepted_if:anotherfield,value,...

The field under validation must be "yes", "on", 1, "1", true, or "true" if another field under validation is equal to a specified value. This is useful for validating "Terms of Service" acceptance or similar fields.

active_url

該驗證欄位在使用 dns_get_record PHP 函式時必須有有效的 A 紀錄或 AAAA 紀錄。在傳送給 dns_get_record 前，主機名稱是從提供的 URL 中使用 parse_url PHP 方法取出的。

after:日期

該驗證欄位必須為給定日期後的日期。日期會使用 PHP 的 strtotime 函式來轉換為有效的 DataTime 實體：

1'start_date' => 'required|date|after:tomorrow'
1'start_date' => 'required|date|after:tomorrow'

除了將日期字串直接傳入 strtotime 取值外，也可以指定另一個欄位來比較日期：

1'finish_date' => 'required|date|after:start_date'
1'finish_date' => 'required|date|after:start_date'

after_or_equal:日期

該驗證欄位的值必須在給定日期之後或等於給定日期。更多資訊請參考 after 規則。

alpha

該驗證欄位必須只由 \p{L} 與 \p{M} 內的 Unicode 的字母字元組成。

若要進一步限制該驗證規則為只允許 ASCII 範圍 (a-z 與 A-Z)，可提供 ascii 選項給該驗證規則：

1'username' => 'alpha:ascii',
1'username' => 'alpha:ascii',

alpha_dash

該驗證欄位必須完全由 \p{L}](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5B%3AL%3A%5D&g=&i=)、\p{M}、\p{N} 內所包含的 Unicode 字母數字字元、以及 ASCII 的減號 (-) 與 ASCII 的底線 (_) 所組成。

若要進一步限制該驗證規則為只允許 ASCII 範圍 (a-z 與 A-Z)，可提供 ascii 選項給該驗證規則：

1'username' => 'alpha_dash:ascii',
1'username' => 'alpha_dash:ascii',

alpha_num

該驗證欄位必須完全由 \p{L}](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5B%3AL%3A%5D&g=&i=)、\p{M} 與 \p{N} 內所包含的 Unicode 字母數字字元所組成。

若要進一步限制該驗證規則為只允許 ASCII 範圍 (a-z 與 A-Z)，可提供 ascii 選項給該驗證規則：

1'username' => 'alpha_num:ascii',
1'username' => 'alpha_num:ascii',

array

該欄位必須為一 PHP array。

若有提供額外的值給 array 規則，則輸入陣列中的每個索引鍵都必須要在提供給該規則的列表值中。在下列的例子中，admin 索引鍵是無效的，因為 admin 不包含在我們提供給 array 規則的數值列表中：

 1use Illuminate\Support\Facades\Validator;
 2 
 3$input = [
 4    'user' => [
 5        'name' => 'Taylor Otwell',
 6        'username' => 'taylorotwell',
 7        'admin' => true,
 8    ],
 9];
10 
11Validator::make($input, [
12    'user' => 'array:name,username',
13]);
 1use Illuminate\Support\Facades\Validator;
 2 
 3$input = [
 4    'user' => [
 5        'name' => 'Taylor Otwell',
 6        'username' => 'taylorotwell',
 7        'admin' => true,
 8    ],
 9];
10 
11Validator::make($input, [
12    'user' => 'array:name,username',
13]);

一般來說，請總是指定允許出現在陣列中的索引鍵：

ascii

該驗證欄位只能由 7 位元的 ASCII 字元組成。

bail

該欄位中某項驗證規則失敗後，停止驗證該欄位的其他規則。

bail 規則會在遇到驗證失敗時停止驗證該欄位，而 stopOnFirstFailure 方法則會讓 Validator 在遇到一個驗證失敗的時候就停止所有屬性的驗證：

1if ($validator->stopOnFirstFailure()->fails()) {
2    // ...
3}
1if ($validator->stopOnFirstFailure()->fails()) {
2    // ...
3}

before:日期

驗證欄位必須為給定日期之前的日期。該日期會被傳給 PHP 的 strtotime 函式，以轉換為有效的 DateTime 實體。此外，與 after 規則一樣，我們也可以提供驗證欄位中的另一個欄位來作為 日期 的值。

before_or_equal:日期

驗證欄位必須為給定日期或給定日期之前的日期。該日期會被傳給 PHP 的 strtotime 函式，以轉換為有效的 DateTime 實體。此外，與 after 規則一樣，我們也可以提供驗證欄位中的另一個欄位來作為 日期 的值。

between:最小值,最大值

該驗證欄位的大小必須介於給定的 最小值 與 最大值 之間 (含)。字串、數字、陣列、與檔案會使用與 size 規則相同的方法計算大小。

boolean

該驗證欄位必須能被轉為布林值。可接受的輸入為 true, false, 1, 0, "1", 與 "0"。

confirmed

該驗證欄位必須與 {欄位}_confirmation 相符合。舉例來說，若正在驗證的欄位是 password，則輸入中必須有相符的 password_confirmation 欄位。

current_password

驗證欄位必須符合目前登入使用者的密碼。可以使用規則的第一個參數來指定認證 Guard。

1'password' => 'current_password:api'
1'password' => 'current_password:api'

date

驗證欄位在依照 strtotime PHP 函式時，必須是有效且非相對的日期。

date_equals:日期

該驗證欄位必須為給定日期或給定日期後的日期。日期會使用 PHP 的 strtotime 函式來轉換為有效的 DataTime 實體：

date_format:格式,...

驗證欄位必須符合其中一個給定的 格式。驗證欄位時只能使用 date 或 date_format 擇一，不可同時使用。該驗證規則支援 PHP DateTime 類別支援的所有格式。

decimal:最小值,最大值

該驗證欄位必須為數字 (Numeric)，且必須包含特定位數的小數點：

1// Must have exactly two decimal places (9.99)...
2'price' => 'decimal:2'
3 
4// Must have between 2 and 4 decimal places...
5'price' => 'decimal:2,4'
1// Must have exactly two decimal places (9.99)...
2'price' => 'decimal:2'
3 
4// Must have between 2 and 4 decimal places...
5'price' => 'decimal:2,4'

declined

The field under validation must be "no", "off", 0, "0", false, or "false".

declined_if:另一個欄位,值,...

The field under validation must be "no", "off", 0, "0", false, or "false" if another field under validation is equal to a specified value.

different:欄位

該驗證欄位必須與 欄位 的值不同。

digits:值

要驗證的整數的長度必須完全符合 值。

digits_between:最小值,最大值

要驗證的整數長度必須介於給定的 最小值 與 最大值。

dimensions

該驗證欄位必須為一張圖片，且必須符合規則參數所指定的長寬限制：

1'avatar' => 'dimensions:min_width=100,min_height=200'
1'avatar' => 'dimensions:min_width=100,min_height=200'

可用的條件限制為：最小寬度 min_width、最大寬度 max_width、最小高度 min_height、最大高度 max_height、寬度 width、高度 height、長寬比 ratio。

長寬比 ratio 以寬除以高來呈現。可以使用如 3/2 這樣的分數，或是如 1.5 這樣的浮點數來表示：

1'avatar' => 'dimensions:ratio=3/2'
1'avatar' => 'dimensions:ratio=3/2'

由於這個規則要求多個引數，所以也可以使用 Rule::dimensions 方法來流暢地建立規則：

1use Illuminate\Support\Facades\Validator;
2use Illuminate\Validation\Rule;
3 
4Validator::make($data, [
5    'avatar' => [
6        'required',
7        Rule::dimensions()->maxWidth(1000)->maxHeight(500)->ratio(3 / 2),
8    ],
9]);
1use Illuminate\Support\Facades\Validator;
2use Illuminate\Validation\Rule;
3 
4Validator::make($data, [
5    'avatar' => [
6        'required',
7        Rule::dimensions()->maxWidth(1000)->maxHeight(500)->ratio(3 / 2),
8    ],
9]);

distinct

在驗證陣列時，該驗證欄位必須不含重複的值：

1'foo.*.id' => 'distinct'
1'foo.*.id' => 'distinct'

Distinct 預設使用鬆散的 (Loose) 變數比較。若要使用嚴格 (Strict) 比較，可在驗證規則定義中加上 strict 參數：

1'foo.*.id' => 'distinct:strict'
1'foo.*.id' => 'distinct:strict'

可以將 ignore_case 加到驗證規則的參數內來讓該規則忽略大小寫差異：

1'foo.*.id' => 'distinct:ignore_case'
1'foo.*.id' => 'distinct:ignore_case'

doesnt_start_with:foo,bar,...

該驗證欄位不可以任何給定的值開頭。

doesnt_end_with:foo,bar,...

該驗證欄位不可以任何給定的值結尾。

email

驗證欄位必須為 E-Mail 位址格式。該驗證規則使用 egulias/email-validator 套件來驗證 E-Mail位址。預設情況下，使用 RFCValidation Validator，不過，也可以自訂套用其他驗證風格：

1'email' => 'email:rfc,dns'
1'email' => 'email:rfc,dns'

上方的例子會套用 RFCValidation 與 DNSCheckValidation 驗證。此處列出了所有可套用的驗證風格：

filter Validator 使用 PHP 的 filter_var 函式，是隨 Laravel 提供的 Validator。在 Laravel 5.8 以前是 Laravel 的預設 E-Mail 驗證行為。

ends_with:foo,bar,...

該驗證欄位必須以其中一個給定的值結尾。

enum

The Enum rule is a class based rule that validates whether the field under validation contains a valid enum value. The Enum rule accepts the name of the enum as its only constructor argument. When validating primitive values, a backed Enum should be provided to the Enum rule:

1use App\Enums\ServerStatus;
2use Illuminate\Validation\Rule;
3 
4$request->validate([
5    'status' => [Rule::enum(ServerStatus::class)],
6]);
1use App\Enums\ServerStatus;
2use Illuminate\Validation\Rule;
3 
4$request->validate([
5    'status' => [Rule::enum(ServerStatus::class)],
6]);

The Enum rule's only and except methods may be used to limit which enum cases should be considered valid:

1Rule::enum(ServerStatus::class)
2    ->only([ServerStatus::Pending, ServerStatus::Active]);
3 
4Rule::enum(ServerStatus::class)
5    ->except([ServerStatus::Pending, ServerStatus::Active]);
1Rule::enum(ServerStatus::class)
2    ->only([ServerStatus::Pending, ServerStatus::Active]);
3 
4Rule::enum(ServerStatus::class)
5    ->except([ServerStatus::Pending, ServerStatus::Active]);

The when method may be used to conditionally modify the Enum rule:

1use Illuminate\Support\Facades\Auth;
2use Illuminate\Validation\Rule;
3 
4Rule::enum(ServerStatus::class)
5    ->when(
6        Auth::user()->isAdmin(),
7        fn ($rule) => $rule->only(...),
8        fn ($rule) => $rule->only(...),
9    );
1use Illuminate\Support\Facades\Auth;
2use Illuminate\Validation\Rule;
3 
4Rule::enum(ServerStatus::class)
5    ->when(
6        Auth::user()->isAdmin(),
7        fn ($rule) => $rule->only(...),
8        fn ($rule) => $rule->only(...),
9    );

exclude

validate 或 validated 方法回傳的 Request 資料中會排除此驗證欄位。

exclude_if:另一欄位,值

若 另一欄位 欄位的值是 值，則 validate 或 validated 方法回傳的 Request 資料中會排除此驗證欄位。

若有需要使用複雜的邏輯條件來排除欄位，可使用 Rule::excludeIf 方法。該方法接受一個布林值或閉包。傳入閉包時，該閉包應回傳 true 或 false，來判斷該驗證欄位是否要被排除：

 1use Illuminate\Support\Facades\Validator;
 2use Illuminate\Validation\Rule;
 3 
 4Validator::make($request->all(), [
 5    'role_id' => Rule::excludeIf($request->user()->is_admin),
 6]);
 7 
 8Validator::make($request->all(), [
 9    'role_id' => Rule::excludeIf(fn () => $request->user()->is_admin),
10]);
 1use Illuminate\Support\Facades\Validator;
 2use Illuminate\Validation\Rule;
 3 
 4Validator::make($request->all(), [
 5    'role_id' => Rule::excludeIf($request->user()->is_admin),
 6]);
 7 
 8Validator::make($request->all(), [
 9    'role_id' => Rule::excludeIf(fn () => $request->user()->is_admin),
10]);

exclude_unless:另一欄位,值

除非 另一欄位 為 值，否則 validate 或 validated 方法回傳的 Request 資料中將不會排除該驗證欄位。若 值 為 null (exclude_unless:name,null)，則除非要比較的欄位為 null 或 Request 資料中沒有要比較的欄位，否則該驗證欄位將不會被排除。

exclude_with:anotherfield

若 另一欄位 存在，則 validate 或 validated 方法回傳的 Request 資料中將排除該驗證欄位。

exclude_without:另一欄位

若 另一欄位 不存在，則 validate 或 validated 方法回傳的 Request 資料中將排除該驗證欄位。

exists:資料表,欄位

該驗證欄位必須在給定資料庫資料表中存在。

Basic Usage of Exists Rule

1'state' => 'exists:states'
1'state' => 'exists:states'

若未指定 column 欄位，則會該驗證欄位的名稱。因此，在這個例子中，本規則會驗證 states 資料表中是否包含有一筆 state 欄位值符合 Request 中 state 屬性值的紀錄。

Specifying a Custom Column Name

也可以顯式指定本驗證規則要使用的資料庫欄位名稱。只需要將欄位名稱放在資料表名稱後即可：

1'state' => 'exists:states,abbreviation'
1'state' => 'exists:states,abbreviation'

有時候，我們可能會需要指定 exists 查詢使用的資料庫連線。為此，我們只要在資料表名稱前方加上連線名稱即可：

1'email' => 'exists:connection.staff,email'
1'email' => 'exists:connection.staff,email'

除了直接指定資料表名稱外，也可以指定要用來判斷資料表名稱的 Eloquent Model：

1'user_id' => 'exists:App\Models\User,id'
1'user_id' => 'exists:App\Models\User,id'

若想自訂該驗證規則執行的查詢，可以使用 Rule 類別來流暢地定義該規則。在這個範例中，我們還會使用陣列來指定驗證規則，而不是使用 | 字元來區分各個規則：

 1use Illuminate\Database\Query\Builder;
 2use Illuminate\Support\Facades\Validator;
 3use Illuminate\Validation\Rule;
 4 
 5Validator::make($data, [
 6    'email' => [
 7        'required',
 8        Rule::exists('staff')->where(function (Builder $query) {
 9            return $query->where('account_id', 1);
10        }),
11    ],
12]);
 1use Illuminate\Database\Query\Builder;
 2use Illuminate\Support\Facades\Validator;
 3use Illuminate\Validation\Rule;
 4 
 5Validator::make($data, [
 6    'email' => [
 7        'required',
 8        Rule::exists('staff')->where(function (Builder $query) {
 9            return $query->where('account_id', 1);
10        }),
11    ],
12]);

只要在 exists 方法的第二個引數上提供欄位名稱，就可以明顯指定 Rule::exists 方法所產生的 exists 規則要使用的資料庫欄位名稱：

1'state' => Rule::exists('states', 'abbreviation'),
1'state' => Rule::exists('states', 'abbreviation'),

extensions:foo,bar,...

The file under validation must have a user-assigned extension corresponding to one of the listed extensions:

1'photo' => ['required', 'extensions:jpg,png'],
1'photo' => ['required', 'extensions:jpg,png'],

file

該驗證欄位必須為一成功上傳的檔案。

filled

當該驗證欄位存在時，不可為空。

gt:欄位

The field under validation must be greater than the given field or value. The two fields must be of the same type. Strings, numerics, arrays, and files are evaluated using the same conventions as the size rule.

gte:欄位

The field under validation must be greater than or equal to the given field or value. The two fields must be of the same type. Strings, numerics, arrays, and files are evaluated using the same conventions as the size rule.

hex_color

The field under validation must contain a valid color value in hexadecimal format.

image

該驗證欄位必須為一圖片 (jpg, jpeg, png, bmp, gif, svg, 或 webp)。

in:foo,bar,...

該驗證欄位必須要包含在給定的列表值中。使用這個規則時，我們常常需要對陣列 implode，所以我們還能使用 Rule::in 方法來流暢地建立該規則：

1use Illuminate\Support\Facades\Validator;
2use Illuminate\Validation\Rule;
3 
4Validator::make($data, [
5    'zones' => [
6        'required',
7        Rule::in(['first-zone', 'second-zone']),
8    ],
9]);
1use Illuminate\Support\Facades\Validator;
2use Illuminate\Validation\Rule;
3 
4Validator::make($data, [
5    'zones' => [
6        'required',
7        Rule::in(['first-zone', 'second-zone']),
8    ],
9]);

若與 array 規則一起使用 in 規則，則輸入陣列中的每個值都必須要包含在提供給 in 規則的列表值中。在下面的例子中，輸入陣列內的 LAS 機場代碼是無效的，因為提供給 in 規則的機場列表中未包含 LAS：

 1use Illuminate\Support\Facades\Validator;
 2use Illuminate\Validation\Rule;
 3 
 4$input = [
 5    'airports' => ['NYC', 'LAS'],
 6];
 7 
 8Validator::make($input, [
 9    'airports' => [
10        'required',
11        'array',
12    ],
13    'airports.*' => Rule::in(['NYC', 'LIT']),
14]);
 1use Illuminate\Support\Facades\Validator;
 2use Illuminate\Validation\Rule;
 3 
 4$input = [
 5    'airports' => ['NYC', 'LAS'],
 6];
 7 
 8Validator::make($input, [
 9    'airports' => [
10        'required',
11        'array',
12    ],
13    'airports.*' => Rule::in(['NYC', 'LIT']),
14]);

in_array:另一欄位.*

該驗證欄位的值必須存在於 另一欄位 的值中。

integer

該驗證欄位必須為整數。

ip

該驗證欄位必須為一 IP 位址。

ipv4

該驗證欄位必須為一 IPv4 位址。

ipv6

該驗證欄位必須為一 IPv6 位址。

json

該驗證欄位必須為有效的 JSON 字串。

lt:欄位

該驗證欄位必須小於給定的 欄位。這兩個欄位必須為相同型別。字串、數字、陣列、檔案等，將使用與 size 規則相同的方式計算長度。

lte:欄位

該驗證欄位必須小於或等於給定的 欄位。這兩個欄位必須為相同型別。字串、數字、陣列、檔案等，將使用與 size 規則相同的方式計算長度。

lowercase

該驗證欄位必須為小寫字母。

mac_address

該驗證欄位必須為一 MAC 位址。

max:值

該驗證欄位必須小於或等於最大值 值。字串、數字、陣列、檔案等會使用與 size 規則相同的方法計算大小。

max_digits:值

要驗證的整數位數必須小於 值。

mimetypes:text/plain,...

該驗證欄位的檔案必須為其中一個給定的 MIME 型別：

1'video' => 'mimetypes:video/avi,video/mpeg,video/quicktime'
1'video' => 'mimetypes:video/avi,video/mpeg,video/quicktime'

若要判斷上傳檔案的 MIME 類型，Laravel 會讀取該檔案的內容，並嘗試推測 MIME 類型。推測的 MIME 類型可能會與用戶端提供的 MIME 類型不同。

mimes:foo,bar,...

The file under validation must have a MIME type corresponding to one of the listed extensions:

1'photo' => 'mimes:jpg,bmp,png'
1'photo' => 'mimes:jpg,bmp,png'

雖然我們只需要指定副檔名，不過這個規則會讀取該檔案的內容並判斷 MIME 類型，再實際去驗證 MIME 類型。可以在下列位置找到一組 MIME 類型與其對應副檔名的列表：

https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types

MIME Types and Extensions

This validation rule does not verify agreement between the MIME type and the extension the user assigned to the file. For example, the mimes:png validation rule would consider a file containing valid PNG content to be a valid PNG image, even if the file is named photo.txt. If you would like to validate the user-assigned extension of the file, you may use the extensions rule.

min:值

該驗證欄位必須有最小值 最小值。字串、數字、陣列、與檔案會使用與 size 規則相同的方法計算大小。

min_digits:值

要驗證的整數位數必須大於 值。

multiple_of:值

該驗證欄位必須為 值 的倍數。

missing

要驗證的欄位不可存在於輸入資料中。

missing_if:另一欄位,值,...

若 另一欄位 欄位為給定的其中一個 值 時，該驗證欄位不可存在。

missing_unless:另一欄位,值

除非 另一欄位 欄位為給定的其中一個 值 時，否則該驗證欄位不可存在。

missing_with:foo,bar,...

只有在 任一指定的其他欄位存在時，該驗證欄位不可存在。

missing_with_all:foo,bar,...

只有在 所有指定的其他欄位都存在時，該驗證欄位不可存在。

not_in:foo,bar,...

該驗證欄位不可包含在給定的列表值中。可使用 Rule::notIn 方法來流暢地建立此規則：

1use Illuminate\Validation\Rule;
2 
3Validator::make($data, [
4    'toppings' => [
5        'required',
6        Rule::notIn(['sprinkles', 'cherries']),
7    ],
8]);
1use Illuminate\Validation\Rule;
2 
3Validator::make($data, [
4    'toppings' => [
5        'required',
6        Rule::notIn(['sprinkles', 'cherries']),
7    ],
8]);

not_regex:格式

該驗證欄位不可符合給定的正規表示式 (Regular Expression)。

在這個規則內部，使用了 PHP 的 preg_match 函式。指定的規則必須符合 preg_match 所要求的格式，因此也必須包含有效的分隔字元(Delimiter)。例如：'email' => 'not_regex:/^.+$/i'。

nullable

該驗證欄位可為 null。。

numeric

該驗證欄位必須為數字 (Numeric)。

present

要驗證的欄位必須存在於輸入資料中。

present_if:anotherfield,value,...

The field under validation must be present if the anotherfield field is equal to any value.

present_unless:anotherfield,value

The field under validation must be present unless the anotherfield field is equal to any value.

present_with:foo,bar,...

The field under validation must be present only if any of the other specified fields are present.

present_with_all:foo,bar,...

The field under validation must be present only if all of the other specified fields are present.

prohibited

要驗證的欄位必須不存在或為空。當欄位符合下列條件時，將視該欄位為空：

prohibited_if:另一欄位,值,...

若 另一欄位 相符與任意的 值，則要驗證的欄位必須不存在或為空。當欄位滿足下列條件時，將視該欄位為空：

若有需要使用複雜的邏輯條件來禁止欄位，可使用 Rule::prohibitedIf 方法。該方法接受一個布林值或閉包。傳入閉包時，該閉包應回傳 true 或 false，來判斷該驗證欄位是否要被禁止：

 1use Illuminate\Support\Facades\Validator;
 2use Illuminate\Validation\Rule;
 3 
 4Validator::make($request->all(), [
 5    'role_id' => Rule::prohibitedIf($request->user()->is_admin),
 6]);
 7 
 8Validator::make($request->all(), [
 9    'role_id' => Rule::prohibitedIf(fn () => $request->user()->is_admin),
10]);
 1use Illuminate\Support\Facades\Validator;
 2use Illuminate\Validation\Rule;
 3 
 4Validator::make($request->all(), [
 5    'role_id' => Rule::prohibitedIf($request->user()->is_admin),
 6]);
 7 
 8Validator::make($request->all(), [
 9    'role_id' => Rule::prohibitedIf(fn () => $request->user()->is_admin),
10]);

prohibited_unless:另一欄位,值,...