驗證 (Validation)

簡介 (Introduction)

Laravel 提供了幾種不同的方法來驗證應用程式的傳入資料。最常見的是使用所有傳入 HTTP 請求都可用的 validate 方法。但是，我們也將討論其他驗證方法。

Laravel 包含了各種方便的驗證規則，你可以將其應用於資料，甚至提供了驗證值在給定資料庫資料表中是否唯一的功能。我們將詳細介紹每個驗證規則，以便你熟悉 Laravel 的所有驗證功能。

驗證快速入門 (Validation Quickstart)

為了了解 Laravel 強大的驗證功能，讓我們看一個驗證表單並將錯誤訊息顯示給使用者的完整範例。透過閱讀這個高層次的概述，你將能夠對如何使用 Laravel 驗證傳入的請求資料有一個很好的大致了解：

定義路由 (Quick Defining The Routes)

首先，讓我們假設我們在 routes/web.php 檔案中定義了以下路由：

use App\Http\Controllers\PostController;

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

GET 路由將顯示一個表單供使用者建立新的部落格文章，而 POST 路由將把新的部落格文章儲存在資料庫中。

建立控制器 (Quick Creating The Controller)

接下來，讓我們看一個處理這些路由傳入請求的簡單控制器。我們暫時將 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]);
    }
}

編寫驗證邏輯 (Quick Writing The Validation Logic)

現在我們準備在 store 方法中填入驗證新部落格文章的邏輯。為此，我們將使用 Illuminate\Http\Request 物件提供的 validate 方法。如果驗證規則通過，你的程式碼將繼續正常執行；但是，如果驗證失敗，將拋出 Illuminate\Validation\ValidationException 例外，並自動將適當的錯誤回應傳送回使用者。

如果在傳統 HTTP 請求期間驗證失敗，將產生一個重新導向到先前 URL 的回應。如果傳入的請求是 XHR 請求，將回傳一個包含驗證錯誤訊息的 JSON 回應。

為了更深入了解 validate 方法，讓我們回到 store 方法：

/**
 * 儲存新的部落格文章。
 */
public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'title' => 'required|unique:posts|max:255',
        'body' => 'required',
    ]);

    // 部落格文章有效...

    return redirect('/posts');
}

如你所見，驗證規則被傳遞給 validate 方法。別擔心 - 所有可用的驗證規則都已記錄在案。同樣，如果驗證失敗，將自動產生適當的回應。如果驗證通過，我們的控制器將繼續正常執行。

或者，驗證規則可以指定為規則陣列，而不是單個 | 分隔的字串：

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

此外，你可以使用 validateWithBag 方法來驗證請求並將任何錯誤訊息儲存在命名錯誤包中：

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

在第一次驗證失敗時停止 (Stopping On First Validation Failure)

有時你可能希望在屬性第一次驗證失敗後停止執行驗證規則。為此，請將 bail 規則指派給該屬性：

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

在此範例中，如果 title 屬性上的 unique 規則失敗，則不會檢查 max 規則。規則將按照指派的順序進行驗證。

關於巢狀屬性的說明 (A Note On Nested Attributes)

如果傳入的 HTTP 請求包含「巢狀」欄位資料，你可以使用「點」語法在驗證規則中指定這些欄位：

$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',
]);

顯示驗證錯誤 (Quick Displaying The Validation Errors)

那麼，如果傳入的請求欄位未通過給定的驗證規則會發生什麼？如前所述，Laravel 將自動將使用者重新導向回他們先前的位置。此外，所有驗證錯誤和請求輸入將自動快閃到 Session。

Illuminate\View\Middleware\ShareErrorsFromSession 中介軟體會將 $errors 變數與應用程式的所有視圖共用，該中介軟體由 web 中介軟體群組提供。當應用此中介軟體時，$errors 變數將始終在你的視圖中可用，讓你可以方便地假設 $errors 變數始終已定義並可安全使用。$errors 變數將是 Illuminate\Support\MessageBag 的實例。有關使用此物件的更多資訊，請查看其文件。

因此，在我們的範例中，當驗證失敗時，使用者將被重新導向到我們控制器的 create 方法，讓我們可以在視圖中顯示錯誤訊息：

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

<h1>Create Post</h1>

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

<!-- Create Post Form -->

自訂錯誤訊息 (Quick Customizing The Error Messages)

Laravel 的內建驗證規則都有一個錯誤訊息，位於應用程式的 lang/en/validation.php 檔案中。如果你的應用程式沒有 lang 目錄，你可以指示 Laravel 使用 lang:publish Artisan 指令建立它。

在 lang/en/validation.php 檔案中，你會找到每個驗證規則的翻譯項目。你可以根據應用程式的需求自由更改或修改這些訊息。

此外，你可以將此檔案複製到另一個語言目錄，以翻譯應用程式語言的訊息。要了解有關 Laravel 在地化的更多資訊，請查看完整的在地化文件。

[!WARNING] 預設情況下，Laravel 應用程式骨架不包含 lang 目錄。如果你想自訂 Laravel 的語言檔案，你可以透過 lang:publish Artisan 指令發佈它們。

XHR 請求與驗證 (Quick Xhr Requests And Validation)

在此範例中，我們使用傳統表單將資料傳送到應用程式。但是，許多應用程式從 JavaScript 驅動的前端接收 XHR 請求。在 XHR 請求期間使用 validate 方法時，Laravel 不會產生重新導向回應。相反，Laravel 會產生一個包含所有驗證錯誤的 JSON 回應。此 JSON 回應將與 422 HTTP 狀態碼一起傳送。

`@error` 指令 (The At Error Directive)

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

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

<label for="title">Post Title</label>

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

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

如果你使用命名錯誤包，你可以將錯誤包的名稱作為第二個參數傳遞給 @error 指令：

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

重新填入表單 (Repopulating Forms)

當 Laravel 因驗證錯誤而產生重新導向回應時，框架將自動將所有請求輸入快閃到 Session。這樣做是為了讓你可以在下一次請求期間方便地存取輸入，並重新填入使用者嘗試提交的表單。

要從先前的請求中檢索快閃輸入，請在 Illuminate\Http\Request 實例上呼叫 old 方法。old 方法將從 Session 中提取先前快閃的輸入資料：

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

Laravel 也提供了一個全域 old 輔助函式。如果你在 Blade 樣板中顯示舊輸入，使用 old 輔助函式重新填入表單會更方便。如果給定欄位沒有舊輸入，將回傳 null：

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

關於可選欄位的說明 (A Note On Optional Fields)

預設情況下，Laravel 在應用程式的全域中介軟體堆疊中包含了 TrimStrings 和 ConvertEmptyStringsToNull 中介軟體。因此，如果你不希望驗證器將 null 值視為無效，你通常需要將「可選」請求欄位標記為 nullable。例如：

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

在此範例中，我們指定 publish_at 欄位可以是 null 或有效的日期表示。如果未將 nullable 修飾符新增到規則定義中，驗證器將認為 null 是無效的日期。

驗證錯誤回應格式 (Validation Error Response Format)

當你的應用程式拋出 Illuminate\Validation\ValidationException 例外且傳入的 HTTP 請求預期 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 必須是有效的電子郵件地址。"]
  }
}

表單請求驗證 (Form Request Validation)

建立表單請求 (Creating Form Requests)

對於更複雜的驗證情境，你可能希望建立一個「表單請求」。表單請求是封裝了自己的驗證和授權邏輯的自訂請求類別。要建立表單請求類別，你可以使用 make:request Artisan CLI 指令：

php artisan make:request StorePostRequest

產生的表單請求類別將放置在 app/Http/Requests 目錄中。如果此目錄不存在，執行 make:request 指令時將會建立它。Laravel 產生的每個表單請求都有兩個方法：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 服務容器自動解析。

那麼，驗證規則是如何評估的呢？你所要做的就是在控制器方法上型別提示請求。傳入的表單請求會在呼叫控制器方法之前進行驗證，這意味著你不需要在控制器中塞滿任何驗證邏輯：

/**
 * Store a new blog post.
 */
public function store(StorePostRequest $request): RedirectResponse
{
    // 傳入的請求是有效的...

    // 檢索已驗證的輸入資料...
    $validated = $request->validated();

    // 檢索已驗證輸入資料的一部分...
    $validated = $request->safe()->only(['name', 'email']);
    $validated = $request->safe()->except(['name', 'email']);

    // 儲存部落格文章...

    return redirect('/posts');
}

如果驗證失敗，將產生一個重新導向回應，將使用者送回他們先前的位置。錯誤也將快閃到 Session 中，以便顯示。如果請求是 XHR 請求，將回傳一個帶有 422 狀態碼的 HTTP 回應給使用者，其中包含驗證錯誤的 JSON 表示。

[!NOTE] 需要為你的 Inertia 驅動的 Laravel 前端新增即時表單請求驗證嗎？查看 Laravel Precognition。

執行額外驗證 (Performing Additional Validation On Form Requests)

有時你需要在初始驗證完成後執行額外驗證。你可以使用表單請求的 after 方法來完成此操作。

after 方法應回傳一個可呼叫物件或閉包的陣列，這些物件或閉包將在驗證完成後被呼叫。給定的可呼叫物件將接收一個 Illuminate\Validation\Validator 實例，允許你在必要時引發額外的錯誤訊息：

use Illuminate\Validation\Validator;

/**
 * Get the "after" validation callables for the request.
 */
public function after(): array
{
    return [
        function (Validator $validator) {
            if ($this->somethingElseIsInvalid()) {
                $validator->errors()->add(
                    'field',
                    'Something is wrong with this field!'
                );
            }
        }
    ];
}

如前所述，after 方法回傳的陣列也可以包含可呼叫類別。這些類別的 __invoke 方法將接收一個 Illuminate\Validation\Validator 實例：

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

/**
 * Get the "after" validation callables for the request.
 */
public function after(): array
{
    return [
        new ValidateUserStatus,
        new ValidateShippingTime,
        function (Validator $validator) {
            //
        }
    ];
}

在第一次驗證失敗時停止 (Request Stopping On First Validation Rule Failure)

透過在你的請求類別中新增 stopOnFirstFailure 屬性，你可以通知驗證器一旦發生單個驗證失敗，就應停止驗證所有屬性：

/**
 * Indicates if the validator should stop on the first rule failure.
 *
 * @var bool
 */
protected $stopOnFirstFailure = true;

自訂重新導向位置 (Customizing The Redirect Location)

當表單請求驗證失敗時，將產生一個重新導向回應，將使用者送回他們先前的位置。但是，你可以自由自訂此行為。為此，請在你的表單請求上定義 $redirect 屬性：

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

或者，如果你想將使用者重新導向到命名路由，你可以定義 $redirectRoute 屬性：

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

授權表單請求 (Authorizing Form Requests)

表單請求類別還包含一個 authorize 方法。在此方法中，你可以判斷經過身份驗證的使用者是否確實有權限更新給定資源。例如，你可以判斷使用者是否確實擁有他們嘗試更新的部落格留言。最有可能的是，你將在此方法中與你的授權閘道和策略進行互動：

use App\Models\Comment;

/**
 * 判斷使用者是否被授權發出此請求。
 */
public function authorize(): bool
{
    $comment = Comment::find($this->route('comment'));

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

由於所有表單請求都繼承了基礎 Laravel 請求類別，我們可以使用 user 方法來存取目前經過身份驗證的使用者。另外，請注意上面範例中對 route 方法的呼叫。此方法允許你存取在被呼叫的路由上定義的 URI 參數，例如下面範例中的 {comment} 參數：

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 服務容器自動解析。

自訂錯誤訊息 (Customizing The Error Messages)

你可以透過覆寫 messages 方法來自訂表單請求使用的錯誤訊息。此方法應回傳屬性 / 規則對及其對應錯誤訊息的陣列：

/**
 * 取得已定義驗證規則的錯誤訊息。
 *
 * @return array<string, string>
 */
public function messages(): array
{
    return [
        'title.required' => 'A title is required',
        'body.required' => 'A message is required',
    ];
}

自訂驗證屬性 (Customizing The Validation Attributes)

許多 Laravel 的內建驗證規則錯誤訊息都包含 :attribute 佔位符。如果你希望驗證訊息的 :attribute 佔位符被替換為自訂屬性名稱，你可以透過覆寫 attributes 方法來指定自訂名稱。此方法應回傳屬性 / 名稱對的陣列：

/**
 * 取得驗證器錯誤的自訂屬性。
 *
 * @return array<string, string>
 */
public function attributes(): array
{
    return [
        'email' => 'email address',
    ];
}

準備驗證輸入 (Preparing Input For Validation)

如果你需要在應用驗證規則之前準備或清理來自請求的任何資料，你可以使用 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']);
}

手動建立驗證器 (Manually Creating Validators)

如果你不想在請求上使用 validate 方法，你可以使用 Validator Facade 手動建立驗證器實例。Facade 上的 make 方法會產生一個新的驗證器實例：

<?php

namespace App\Http\Controllers;

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

class PostController extends Controller
{
    /**
     * 儲存新的部落格文章。
     */
    public function store(Request $request): RedirectResponse
    {
        $validator = Validator::make($request->all(), [
            'title' => 'required|unique:posts|max:255',
            'body' => 'required',
        ]);

        if ($validator->fails()) {
            return redirect('/post/create')
                ->withErrors($validator)
                ->withInput();
        }

        // Retrieve the validated input...
        $validated = $validator->validated();

        // Retrieve a portion of the validated input...
        $validated = $validator->safe()->only(['name', 'email']);
        $validated = $validator->safe()->except(['name', 'email']);

        // Store the blog post...

        return redirect('/posts');
    }
}

傳遞給 make 方法的第一個參數是正在驗證的資料。第二個參數是應應用於資料的驗證規則陣列。

在判斷請求驗證是否失敗後，你可以使用 withErrors 方法將錯誤訊息快閃到 Session。使用此方法時，$errors 變數將在重新導向後自動與你的視圖共用，讓你輕鬆地將其顯示給使用者。withErrors 方法接受驗證器、MessageBag 或 PHP array。

在第一次驗證失敗時停止

stopOnFirstFailure 方法將通知驗證器一旦發生單個驗證失敗，就應停止驗證所有屬性：

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

自動重新導向 (Automatic Redirection)

如果你想手動建立驗證器實例，但仍想利用 HTTP 請求的 validate 方法提供的自動重新導向，你可以在現有的驗證器實例上呼叫 validate 方法。如果驗證失敗，使用者將自動被重新導向，或者在 XHR 請求的情況下，將回傳 JSON 回應：

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

如果驗證失敗，你可以使用 validateWithBag 方法將錯誤訊息儲存在命名錯誤包中：

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

命名錯誤包 (Named Error Bags)

如果你的單個頁面上有由多個表單，你可能希望命名包含驗證錯誤的 MessageBag，以便檢索特定表單的錯誤訊息。為此，請將名稱作為第二個參數傳遞給 withErrors：

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

然後你可以從 $errors 變數存取命名的 MessageBag 實例：

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

自訂錯誤訊息 (Manual Customizing The Error Messages)

如果需要，你可以提供自訂錯誤訊息，讓驗證器實例使用這些訊息代替 Laravel 提供的預設錯誤訊息。有幾種方法可以指定自訂訊息。首先，你可以將自訂訊息作為第三個參數傳遞給 Validator::make 方法：

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

在此範例中，:attribute 佔位符將被替換為正在驗證的欄位的實際名稱。你也可以在驗證訊息中使用其他佔位符。例如：

$messages = [
    'same' => 'The :attribute and :other must match.',
    'size' => 'The :attribute must be exactly :size.',
    'between' => ':attribute 的值 :input 必須介於 :min - :max 之間。',
    'in' => 'The :attribute must be one of the following types: :values',
];

為給定屬性指定自訂訊息 (Specifying A Custom Message For A Given Attribute)

有時你可能希望僅為特定屬性指定自訂錯誤訊息。你可以使用「點」符號來執行此操作。首先指定屬性名稱，然後是規則：

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

指定自訂屬性值 (Specifying Custom Attribute Values)

許多 Laravel 的內建錯誤訊息都包含一個 :attribute 佔位符，該佔位符將被替換為正在驗證的欄位或屬性的名稱。若要自訂用於替換特定欄位這些佔位符的值，你可以將自訂屬性陣列作為第四個參數傳遞給 Validator::make 方法：

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

執行額外驗證 (Performing Additional Validation)

有時你需要在初始驗證完成後執行額外驗證。你可以使用驗證器的 after 方法來完成此操作。after 方法接受一個閉包或可呼叫物件的陣列，這些物件將在驗證完成後被呼叫。給定的可呼叫物件將接收一個 Illuminate\Validation\Validator 實例，允許你在必要時引發額外的錯誤訊息：

use Illuminate\Support\Facades\Validator;

$validator = Validator::make(/* ... */);

$validator->after(function ($validator) {
    if ($this->somethingElseIsInvalid()) {
        $validator->errors()->add(
            'field', 'Something is wrong with this field!'
        );
    }
});

if ($validator->fails()) {
    // ...
}

如前所述，after 方法也接受可呼叫物件的陣列，如果你的「驗證後」邏輯封裝在可呼叫類別中，這將特別方便，這些類別將透過其 __invoke 方法接收 Illuminate\Validation\Validator 實例：

use App\Validation\ValidateShippingTime;
use App\Validation\ValidateUserStatus;

$validator->after([
    new ValidateUserStatus,
    new ValidateShippingTime,
    function ($validator) {
        // ...
    },
]);

處理已驗證的輸入 (Working With Validated Input)

在使用表單請求或手動建立的驗證器實例驗證傳入的請求資料後，你可能希望檢索實際經過驗證的傳入請求資料。這可以透過幾種方式完成。首先，你可以在表單請求或驗證器實例上呼叫 validated 方法。此方法回傳已驗證資料的陣列：

$validated = $request->validated();

$validated = $validator->validated();

或者，你可以在表單請求或驗證器實例上呼叫 safe 方法。此方法回傳 Illuminate\Support\ValidatedInput 的實例。此物件公開 only、except 和 all 方法，以檢索已驗證資料的子集或整個已驗證資料陣列：

$validated = $request->safe()->only(['name', 'email']);

$validated = $request->safe()->except(['name', 'email']);

$validated = $request->safe()->all();

此外，Illuminate\Support\ValidatedInput 實例可以像陣列一樣進行迭代和存取：

// Validated data may be iterated...
foreach ($request->safe() as $key => $value) {
    // ...
}

// Validated data may be accessed as an array...
$validated = $request->safe();

$email = $validated['email'];

If you would like to add additional fields to the validated data, you may call the merge method:

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

If you would like to retrieve the validated data as a collection instance, you may call the collect method:

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

處理錯誤訊息 (Working With Error Messages)

在 Validator 實例上呼叫 errors 方法後，你將收到一個 Illuminate\Support\MessageBag 實例，該實例具有各種方便的方法來處理錯誤訊息。自動提供給所有視圖的 $errors 變數也是 MessageBag 類別的實例。

檢索欄位的第一個錯誤訊息 (Retrieving The First Error Message For A Field)

要檢索給定欄位的第一個錯誤訊息，請使用 first 方法：

$errors = $validator->errors();

echo $errors->first('email');

檢索欄位的所有錯誤訊息 (Retrieving All Error Messages For A Field)

如果你需要檢索給定欄位的所有訊息陣列，請使用 get 方法：

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

如果你正在驗證陣列表單欄位，你可以使用 * 字元檢索每個陣列元素的所有訊息：

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

檢索所有欄位的所有錯誤訊息 (Retrieving All Error Messages For All Fields)

要檢索所有欄位的所有訊息陣列，請使用 all 方法：

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

判斷欄位是否存在訊息 (Determining If Messages Exist For A Field)

has 方法可用於判斷給定欄位是否存在任何錯誤訊息：

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

在語言檔案中指定自訂訊息 (Specifying Custom Messages In Language Files)

在 lang/en/validation.php 檔案中，你會找到每個驗證規則的翻譯項目。你可以根據應用程式的需求自由更改或修改這些訊息。

此外，你可以將此檔案複製到另一個語言目錄，以翻譯應用程式語言的訊息。要了解有關 Laravel 在地化的更多資訊，請查看完整的在地化文件。

[!WARNING] 預設情況下，Laravel 應用程式骨架不包含 lang 目錄。如果你想自訂 Laravel 的語言檔案，你可以透過 lang:publish Artisan 指令發佈它們。

特定屬性的自訂訊息 (Custom Messages For Specific Attributes)

你可以在應用程式的 lang/xx/validation.php 語言檔案的 custom 陣列中新增訊息自訂，以自訂用於指定屬性或規則組合的錯誤訊息：

'custom' => [
    'email' => [
        'required' => 'We need to know your email address!',
        'max' => 'Your email address is too long!'
    ],
],

在語言檔案中指定屬性 (Specifying Attribute In Language Files)

許多 Laravel 的內建錯誤訊息都包含一個 :attribute 佔位符，該佔位符將被替換為正在驗證的欄位或屬性的名稱。如果你希望驗證訊息的 :attribute 佔位符被替換為自訂屬性名稱，你可以在 lang/en/validation.php 語言檔案的 attributes 陣列中指定自訂名稱：

'attributes' => [
    'email' => 'email address',
],

[!WARNING] 預設情況下，Laravel 應用程式骨架不包含 lang 目錄。如果你想自訂 Laravel 的語言檔案，你可以透過 lang:publish Artisan 指令發佈它們。

在語言檔案中指定值 (Specifying Values In Language Files)

某些 Laravel 的內建驗證規則錯誤訊息包含一個 :value 佔位符，該佔位符將被替換為請求屬性的目前值。有時你可能需要將驗證訊息的 :value 佔位符替換為值的自訂表示。例如，考慮以下規則，該規則指定如果 payment_type 的值為 cc，則需要信用卡號碼：

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

如果此驗證規則失敗，它將產生以下錯誤訊息：

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

你可以透過定義 values 陣列在 lang/en/validation.php 語言檔案中指定自訂值表示，而不是將 cc 顯示為付款類型值：

'values' => [
    'payment_type' => [
        'cc' => 'credit card'
    ],
],

[!WARNING] 預設情況下，Laravel 應用程式骨架不包含 lang 目錄。如果你想自訂 Laravel 的語言檔案，你可以透過 lang:publish Artisan 指令發佈它們。

定義此值後，如果驗證規則失敗，它將產生以下訊息：

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

可用的驗證規則 (Available Validation Rules)

以下是所有可用驗證規則及其功能的列表：

字串

工具

accepted

驗證的欄位必須是 "yes"、"on"、1、"1"、true 或 "true"。這對於驗證「服務條款」接受度或類似欄位很有用。

accepted_if:anotherfield,value,...

如果另一個驗證欄位等於指定值，則驗證的欄位必須是 "yes"、"on"、1、"1"、true 或 "true"。這對於驗證「服務條款」接受度或類似欄位很有用。

active_url

根據 dns_get_record PHP 函式，驗證的欄位必須具有有效的 A 或 AAAA 記錄。在傳遞給 dns_get_record 之前，會使用 parse_url PHP 函式提取提供的 URL 的主機名稱。

after:date

驗證的欄位必須是給定日期之後的值。日期將被傳遞給 strtotime PHP 函式，以便轉換為有效的 DateTime 實例：

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

你可以指定另一個欄位來與日期進行比較，而不是傳遞一個由 strtotime 評估的日期字串：

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

為了方便起見，可以使用流暢的 date 規則建構器來建構基於日期的規則：

use Illuminate\Validation\Rule;

'start_date' => [
    'required',
    Rule::date()->after(today()->addDays(7)),
],

afterToday 和 todayOrAfter 方法可用於流暢地表達日期，並且必須分別在今天之後，或今天或之後：

'start_date' => [
    'required',
    Rule::date()->afterToday(),
],

after_or_equal:date

驗證的欄位必須是給定日期之後或等於給定日期的值。有關更多資訊，請參閱 after 規則。

為了方便起見，可以使用流暢的 date 規則建構器來建構基於日期的規則：

use Illuminate\Validation\Rule;

'start_date' => [
    'required',
    Rule::date()->afterOrEqual(today()->addDays(7)),
],

anyOf

Rule::anyOf 驗證規則允許你指定驗證的欄位必須滿足任何給定的驗證規則集。例如，以下規則將驗證 username 欄位是電子郵件地址或長度至少為 6 個字元的英數字串（包括破折號）：

use Illuminate\Validation\Rule;

'username' => [
    'required',
    Rule::anyOf([
        ['string', 'email'],
        ['string', 'alpha_dash', 'min:6'],
    ]),
],

alpha

驗證的欄位必須完全是包含在 \p{L} 和 \p{M} 中的 Unicode 字母字元。

要將此驗證規則限制為 ASCII 範圍內的字元（a-z 和 A-Z），你可以向驗證規則提供 ascii 選項：

'username' => 'alpha:ascii',

alpha_dash

驗證的欄位必須完全是包含在 \p{L}、\p{M}、\p{N} 中的 Unicode 英數字元，以及 ASCII 破折號（-）和 ASCII 底線（_）。

要將此驗證規則限制為 ASCII 範圍內的字元（a-z、A-Z 和 0-9），你可以向驗證規則提供 ascii 選項：

'username' => 'alpha_dash:ascii',

alpha_num

驗證的欄位必須完全是包含在 \p{L}、\p{M} 和 \p{N} 中的 Unicode 英數字元。

要將此驗證規則限制為 ASCII 範圍內的字元（a-z、A-Z 和 0-9），你可以向驗證規則提供 ascii 選項：

'username' => 'alpha_num:ascii',

array

驗證的欄位必須是 PHP array。

當向 array 規則提供額外值時，輸入陣列中的每個鍵都必須存在於提供給規則的值列表中。在以下範例中，輸入陣列中的 admin 鍵無效，因為它不包含在提供給 array 規則的值列表中：

use Illuminate\Support\Facades\Validator;

$input = [
    'user' => [
        'name' => 'Taylor Otwell',
        'username' => 'taylorotwell',
        'admin' => true,
    ],
];

Validator::make($input, [
    'user' => 'array:name,username',
]);

一般來說，你應該始終指定允許存在於陣列中的陣列鍵。

ascii

驗證的欄位必須完全是 7 位元 ASCII 字元。

bail

在第一次驗證失敗後停止執行該欄位的驗證規則。

雖然 bail 規則僅在遇到驗證失敗時停止驗證特定欄位，但 stopOnFirstFailure 方法將通知驗證器一旦發生單個驗證失敗，就應停止驗證所有屬性：

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

before:date

驗證的欄位必須是給定日期之前的值。日期將被傳遞給 PHP strtotime 函式，以便轉換為有效的 DateTime 實例。此外，就像 after 規則一樣，可以提供另一個驗證欄位的名稱作為 date 的值。

為了方便起見，也可以使用流暢的 date 規則建構器來建構基於日期的規則：

use Illuminate\Validation\Rule;

'start_date' => [
    'required',
    Rule::date()->before(today()->subDays(7)),
],

beforeToday 和 todayOrBefore 方法可用於流暢地表達日期，並且必須分別在今天之前，或今天或之前：

'start_date' => [
    'required',
    Rule::date()->beforeToday(),
],

before_or_equal:date

驗證的欄位必須是給定日期之前或等於給定日期的值。日期將被傳遞給 PHP strtotime 函式，以便轉換為有效的 DateTime 實例。此外，就像 after 規則一樣，可以提供另一個驗證欄位的名稱作為 date 的值。

為了方便起見，也可以使用流暢的 date 規則建構器來建構基於日期的規則：

use Illuminate\Validation\Rule;

'start_date' => [
    'required',
    Rule::date()->beforeOrEqual(today()->subDays(7)),
],

between:min,max

驗證的欄位大小必須在給定的 min 和 max 之間（含）。字串、數字、陣列和檔案的評估方式與 size 規則相同。

boolean

驗證的欄位必須能夠轉換為布林值。接受的輸入為 true、false、1、0、"1" 和 "0"。

你可以使用 strict 參數，僅當欄位值為 true 或 false 時才認為該欄位有效：

'foo' => 'boolean:strict'

confirmed

驗證的欄位必須有一個相符的 {field}_confirmation 欄位。例如，如果驗證的欄位是 password，則輸入中必須存在相符的 password_confirmation 欄位。

你也可以傳遞自訂確認欄位名稱。例如，confirmed:repeat_username 將預期 repeat_username 欄位與驗證的欄位相符。

contains:foo,bar,...

驗證的欄位必須是包含所有給定參數值的陣列。由於此規則通常需要你 implode 一個陣列，因此可以使用 Rule::contains 方法來流暢地建構規則：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'roles' => [
        'required',
        'array',
        Rule::contains(['admin', 'editor']),
    ],
]);

doesnt_contain:foo,bar,...

驗證的欄位必須是不包含任何給定參數值的陣列。由於此規則通常需要你 implode 一個陣列，因此可以使用 Rule::doesntContain 方法來流暢地建構規則：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'roles' => [
        'required',
        'array',
        Rule::doesntContain(['admin', 'editor']),
    ],
]);

current_password

驗證的欄位必須與經過身份驗證的使用者的密碼相符。你可以使用規則的第一個參數指定身份驗證 Guard：

'password' => 'current_password:api'

date

根據 strtotime PHP 函式，驗證的欄位必須是有效的非相對日期。

date_equals:date

驗證的欄位必須等於給定日期。日期將被傳遞給 PHP strtotime 函式，以便轉換為有效的 DateTime 實例。

date_format:format,...

驗證的欄位必須符合給定的 formats 之一。驗證欄位時，你應該使用 date 或 date_format，而不是兩者都用。此驗證規則支援 PHP DateTime 類別支援的所有格式。

為了方便起見，可以使用流暢的 date 規則建構器來建構基於日期的規則：

use Illuminate\Validation\Rule;

'start_date' => [
    'required',
    Rule::date()->format('Y-m-d'),
],

decimal:min,max

驗證的欄位必須是數字，並且必須包含指定的小數位數：

// Must have exactly two decimal places (9.99)...
'price' => 'decimal:2'

// Must have between 2 and 4 decimal places...
'price' => 'decimal:2,4'

declined

驗證的欄位必須是 "no"、"off"、0、"0"、false 或 "false"。

declined_if:anotherfield,value,...

如果另一個驗證欄位等於指定值，則驗證的欄位必須是 "no"、"off"、0、"0"、false 或 "false"。

different:field

驗證的欄位必須具有與 field 不同的值。

digits:value

驗證的整數必須具有 value 的確切長度。

digits_between:min,max

驗證的整數長度必須在給定的 min 和 max 之間。

dimensions

驗證的檔案必須是符合規則參數指定尺寸限制的圖片：

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

可用的限制包括：min_width、max_width、min_height、max_height、width、height、ratio。

ratio 限制應表示為寬度除以高度。這可以透過分數（如 3/2）或浮點數（如 1.5）來指定：

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

由於此規則需要多個參數，因此使用 Rule::dimensions 方法來流暢地建構規則通常更方便：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'avatar' => [
        'required',
        Rule::dimensions()
            ->maxWidth(1000)
            ->maxHeight(500)
            ->ratio(3 / 2),
    ],
]);

distinct

驗證陣列時，驗證的欄位不得有任何重複值：

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

Distinct 預設使用寬鬆的變數比較。要使用嚴格比較，你可以在驗證規則定義中新增 strict 參數：

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

你可以在驗證規則的參數中新增 ignore_case，使規則忽略大小寫差異：

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

doesnt_start_with:foo,bar,...

驗證的欄位不得以給定值之一開頭。

doesnt_end_with:foo,bar,...

驗證的欄位不得以給定值之一結尾。

email

驗證的欄位必須格式化為電子郵件地址。此驗證規則利用 egulias/email-validator 套件來驗證電子郵件地址。預設情況下，應用 RFCValidation 驗證器，但你也可以應用其他驗證樣式：

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

上面的範例將應用 RFCValidation 和 DNSCheckValidation 驗證。以下是你可以應用的驗證樣式的完整列表：

rfc: RFCValidation - 根據支援的 RFC 驗證電子郵件地址。
strict: NoRFCWarningsValidation - 根據支援的 RFC 驗證電子郵件，當發現警告時失敗（例如尾隨句點和多個連續句點）。
dns: DNSCheckValidation - 確保電子郵件地址的網域具有有效的 MX 記錄。
spoof: SpoofCheckValidation - 確保電子郵件地址不包含同形異義字或欺騙性 Unicode 字元。
filter: FilterEmailValidation - 確保電子郵件地址根據 PHP 的 filter_var 函式是有效的。
filter_unicode: FilterEmailValidation::unicode() - 確保電子郵件地址根據 PHP 的 filter_var 函式是有效的，允許某些 Unicode 字元。

為了方便起見，可以使用流暢的規則建構器來建構電子郵件驗證規則：

use Illuminate\Validation\Rule;

$request->validate([
    'email' => [
        'required',
        Rule::email()
            ->rfcCompliant(strict: false)
            ->validateMxRecord()
            ->preventSpoofing()
    ],
]);

[!WARNING] > dns 和 spoof 驗證器需要 PHP intl 擴充功能。

encoding:encoding_type

驗證的欄位必須符合指定的字元編碼。此規則使用 PHP 的 mb_check_encoding 函式來驗證給定檔案或字串值的編碼。為了方便起見，可以使用 Laravel 的流暢檔案規則建構器來建構 encoding 規則：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rules\File;

Validator::validate($input, [
    'attachment' => [
        'required',
        File::types(['csv'])
            ->encoding('utf-8'),
    ],
]);

ends_with:foo,bar,...

驗證的欄位必須以給定值之一結尾。

enum

Enum 規則是基於類別的規則，用於驗證驗證的欄位是否包含有效的列舉值。Enum 規則接受列舉名稱作為其唯一的建構函式參數。驗證原始值時，應向 Enum 規則提供支援的 Enum：

use App\Enums\ServerStatus;
use Illuminate\Validation\Rule;

$request->validate([
    'status' => [Rule::enum(ServerStatus::class)],
]);

Enum 規則的 only 和 except 方法可用於限制哪些列舉案例應被視為有效：

Rule::enum(ServerStatus::class)
    ->only([ServerStatus::Pending, ServerStatus::Active]);

Rule::enum(ServerStatus::class)
    ->except([ServerStatus::Pending, ServerStatus::Active]);

when 方法可用於有條件地修改 Enum 規則：

use Illuminate\Support\Facades\Auth;
use Illuminate\Validation\Rule;

Rule::enum(ServerStatus::class)
    ->when(
        Auth::user()->isAdmin(),
        fn ($rule) => $rule->only(...),
        fn ($rule) => $rule->only(...),
    );

exclude

驗證的欄位將從 validate 和 validated 方法回傳的請求資料中排除。

exclude_if:anotherfield,value

如果 anotherfield 欄位等於 value，則驗證的欄位將從 validate 和 validated 方法回傳的請求資料中排除。

如果需要複雜的條件排除邏輯，你可以利用 Rule::excludeIf 方法。此方法接受布林值或閉包。當給定閉包時，閉包應回傳 true 或 false 以指示是否應排除驗證的欄位：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($request->all(), [
    'role_id' => Rule::excludeIf($request->user()->is_admin),
]);

Validator::make($request->all(), [
    'role_id' => Rule::excludeIf(fn () => $request->user()->is_admin),
]);

exclude_unless:anotherfield,value

除非 anotherfield 欄位等於 value，否則驗證的欄位將從 validate 和 validated 方法回傳的請求資料中排除。如果 value 為 null (exclude_unless:name,null)，則除非比較欄位為 null 或請求資料中缺少比較欄位，否則將排除驗證的欄位。

exclude_with:anotherfield

如果存在 anotherfield 欄位，則驗證的欄位將從 validate 和 validated 方法回傳的請求資料中排除。

exclude_without:anotherfield

如果不存在 anotherfield 欄位，則驗證的欄位將從 validate 和 validated 方法回傳的請求資料中排除。

exists:table,column

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

Exists 規則的基本用法 (Basic Usage Of Exists Rule)

'state' => 'exists:states'

如果未指定 column 選項，將使用欄位名稱。因此，在這種情況下，規則將驗證 states 資料庫資料表是否包含一條記錄，其 state 欄位值與請求的 state 屬性值相符。

指定自訂欄位名稱 (Specifying A Custom Column Name)

你可以透過將資料庫欄位名稱放在資料庫資料表名稱之後，明確指定驗證規則應使用的資料庫欄位名稱：

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

偶爾，你可能需要指定用於 exists 查詢的特定資料庫連線。你可以透過在資料表名稱前加上連線名稱來完成此操作：

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

你可以指定應用於確定資料表名稱的 Eloquent 模型，而不是直接指定資料表名稱：

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

如果你想自訂驗證規則執行的查詢，你可以使用 Rule 類別流暢地定義規則。在此範例中，我們還將驗證規則指定為陣列，而不是使用 | 字元來分隔它們：

use Illuminate\Database\Query\Builder;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'email' => [
        'required',
        Rule::exists('staff')->where(function (Builder $query) {
            $query->where('account_id', 1);
        }),
    ],
]);

你可以透過將欄位名稱作為第二個參數傳遞給 exists 方法，明確指定 Rule::exists 方法產生的 exists 規則應使用的資料庫欄位名稱：

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

有時，你可能希望驗證資料庫中是否存在值陣列。你可以透過將 exists 和 array 規則都新增到正在驗證的欄位來實現此目的：

'states' => ['array', Rule::exists('states', 'abbreviation')],

extensions:foo,bar,...

驗證的檔案必須具有與列出的擴充功能之一相對應的副檔名：

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

[!WARNING] 你不應建立同時明確檢查 extensions 和 mimes 規則的驗證規則。這是因為 extensions 規則從副檔名推斷 MIME 類型，而 mimes 規則從檔案內容推斷 MIME 類型。) rules.

file

驗證的欄位必須是成功上傳的檔案。

filled

當驗證的欄位存在時，它不得為空。

gt:field

驗證的欄位必須大於給定的 field 或 value。這兩個欄位必須是相同類型。字串、數字、陣列和檔案使用與 size 規則相同的約定進行評估。-size) rule.

gte:field

驗證的欄位必須大於或等於給定的 field 或 value。這兩個欄位必須是相同類型。字串、數字、陣列和檔案使用與 size 規則相同的約定進行評估。-size) rule.

hex_color

驗證的欄位必須是十六進位格式的有效顏色。tps://developer.mozilla.org/en-US/docs/Web/CSS/hex-color) format.

image

驗證的檔案必須是圖片（jpg、jpeg、png、bmp、gif、svg 或 webp）。

[!WARNING] 預設情況下，image 規則不允許 SVG 檔案，因為存在 XSS 漏洞的可能性。如果你需要允許 SVG 檔案，你可以將 allow_svg 指令提供給 image 規則 (image:allow_svg)。

in:foo,bar,...

驗證的欄位必須包含在給定的值列表中。由於此規則通常需要你 implode 一個陣列，因此可以使用 Rule::in 方法來流暢地建構規則：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'zones' => [
        'required',
        Rule::in(['first-zone', 'second-zone']),
    ],
]);

當 in 規則與 array 規則結合使用時，輸入陣列中的每個值都必須存在於提供給 in 規則的值列表中。在以下範例中，輸入陣列中的 LAS 機場代碼無效，因為它不包含在提供給 in 規則的機場列表中：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$input = [
    'airports' => ['NYC', 'LAS'],
];

Validator::make($input, [
    'airports' => [
        'required',
        'array',
    ],
    'airports.*' => Rule::in(['NYC', 'LIT']),
]);

in_array:anotherfield.*

驗證的欄位必須存在於 anotherfield 的值中。

in_array_keys:value.*

驗證的欄位必須是一個陣列，其中至少有一個給定的 values 作為陣列中的鍵：

'config' => 'array|in_array_keys:timezone'

integer

驗證的欄位必須是整數。

你可以使用 strict 參數，僅當欄位類型為 integer 時才將其視為有效。具有整數值的字串將被視為無效：

'age' => 'integer:strict'

[!WARNING] 此驗證規則不驗證輸入是否為「整數」變數類型，僅驗證輸入是否為包含整數的字串或數值。PHP's FILTER_VALIDATE_INT rule. If you need to validate the input as being a number please use this rule in combination with the numeric validation rule.

ip

驗證的欄位必須是 IP 地址。

ipv4

驗證的欄位必須是 IPv4 地址。

ipv6

驗證的欄位必須是 IPv6 地址。

json

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

lt:field

驗證的欄位必須小於給定的 field。這兩個欄位必須是相同類型。字串、數字、陣列和檔案使用與 size 規則相同的約定進行評估。-size) rule.

lte:field

驗證的欄位必須小於或等於給定的 field。這兩個欄位必須是相同類型。字串、數字、陣列和檔案使用與 size 規則相同的約定進行評估。-size) rule.

lowercase

驗證的欄位必須是小寫。

list

驗證的欄位必須是一個列表陣列。如果陣列的鍵由從 0 到 count($array) - 1 的連續數字組成，則該陣列被視為列表。

mac_address

驗證的欄位必須是 MAC 位址。

max:value

驗證的欄位必須小於或等於最大 value。字串、數字、陣列和檔案的評估方式與 size 規則相同。

max_digits:value

驗證的整數必須具有最大長度 value。

mimetypes:text/plain,...

驗證的檔案必須符合給定的 MIME 類型之一：

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

為了確定上傳檔案的 MIME 類型，將讀取檔案內容，框架將嘗試猜測 MIME 類型，這可能與客戶端提供的 MIME 類型不同。

mimes:foo,bar,...

驗證的檔案必須具有與列出的擴充功能之一相對應的擴充功能：

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

即使你只需要指定擴充功能，此規則實際上也會透過讀取檔案內容並猜測其 MIME 類型來驗證檔案的 MIME 類型。可以在以下位置找到 MIME 類型及其對應擴充功能的完整列表：

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

MIME 類型和副檔名 (Mime Types And Extensions)

此驗證規則不會驗證 MIME 類型與使用者為檔案指定的副檔名之間的一致性。例如，mimes:png 驗證規則會將包含有效 PNG 內容的檔案視為有效的 PNG 圖片，即使該檔案名為 photo.txt。如果你想驗證使用者為檔案指定的副檔名，可以使用 extensions 規則。

min:value

驗證的欄位必須具有最小 value。字串、數字、陣列和檔案的評估方式與 size 規則相同。

min_digits:value

驗證的整數必須具有最小長度 value。

multiple_of:value

驗證的欄位必須是 value 的倍數。

missing

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

missing_if:anotherfield,value,...

如果 anotherfield 欄位等於任何 value，則驗證的欄位不得存在。

missing_unless:anotherfield,value

除非 anotherfield 欄位等於任何 value，否則驗證的欄位不得存在。

missing_with:foo,bar,...

僅當任何其他指定欄位存在時，驗證的欄位才不得存在。

missing_with_all:foo,bar,...

僅當所有其他指定欄位都存在時，驗證的欄位才不得存在。

not_in:foo,bar,...

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

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'toppings' => [
        'required',
        Rule::notIn(['sprinkles', 'cherries']),
    ],
]);

not_regex:pattern

驗證的欄位不得與給定的正規表示式相符。

在內部，此規則使用 PHP preg_match 函式。指定的模式應遵守 preg_match 所需的相同格式，因此也應包含有效的分隔符號。例如：'email' => 'not_regex:/^.+$/i'。

[!WARNING] 使用 regex / not_regex 模式時，可能有必要在陣列中指定驗證規則，而不是使用 | 分隔符號，特別是如果正規表示式包含 | 字元。

nullable

驗證的欄位可以是 null。這在驗證可能包含 null 值的字串和整數等原始型別時特別有用。

numeric

驗證的欄位必須是數值。

你可以使用 strict 參數，僅當欄位類型為整數或浮點數時才將其視為有效。數值字串將被視為無效：

'amount' => 'numeric:strict'

present

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

present_if:anotherfield,value,...

如果 anotherfield 欄位等於任何 value，則驗證的欄位必須存在。

present_unless:anotherfield,value

除非 anotherfield 欄位等於任何 value，否則驗證的欄位必須存在。

present_with:foo,bar,...

僅當任何其他指定欄位存在時，驗證的欄位才必須存在。

present_with_all:foo,bar,...

僅當所有其他指定欄位都存在時，驗證的欄位才必須存在。

prohibited

驗證的欄位必須不存在或為空。如果符合以下條件之一，則欄位為「空」：

值為 null。
值為空字串。
值為空陣列或空的 Countable 物件。
值為路徑為空的已上傳檔案。

prohibited_if:anotherfield,value,...

如果 anotherfield 欄位等於任何 value，則驗證的欄位必須不存在或為空。如果符合以下條件之一，則欄位為「空」：

值為 null。
值為空字串。
值為空陣列或空的 Countable 物件。
值為路徑為空的已上傳檔案。

如果需要複雜的條件禁止邏輯，你可以利用 Rule::prohibitedIf 方法。此方法接受布林值或閉包。當給定閉包時，閉包應回傳 true 或 false 以指示是否應禁止驗證的欄位：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($request->all(), [
    'role_id' => Rule::prohibitedIf($request->user()->is_admin),
]);

Validator::make($request->all(), [
    'role_id' => Rule::prohibitedIf(fn () => $request->user()->is_admin),
]);

prohibited_if_accepted:anotherfield,...

如果 anotherfield 欄位等於 "yes"、"on"、1、"1"、true 或 "true"，則驗證的欄位必須不存在或為空。

prohibited_if_declined:anotherfield,...

如果 anotherfield 欄位等於 "no"、"off"、0、"0"、false 或 "false"，則驗證的欄位必須不存在或為空。

prohibited_unless:anotherfield,value,...

除非 anotherfield 欄位等於任何 value，否則驗證的欄位必須不存在或為空。如果符合以下條件之一，則欄位為「空」：

值為 null。
值為空字串。
值為空陣列或空的 Countable 物件。
值為路徑為空的已上傳檔案。

prohibits:anotherfield,...

如果驗證的欄位不存在或不為空，則 anotherfield 中的所有欄位都必須不存在或為空。如果符合以下條件之一，則欄位為「空」：

值為 null。
值為空字串。
值為空陣列或空的 Countable 物件。
值為路徑為空的已上傳檔案。

regex:pattern

驗證的欄位必須符合給定的正規表示式。

在內部，此規則使用 PHP preg_match 函式。指定的模式應遵守 preg_match 所需的相同格式，因此也應包含有效的分隔符號。例如：'email' => 'regex:/^.+@.+$/i'。

[!WARNING] 使用 regex / not_regex 模式時，可能有必要在陣列中指定規則，而不是使用 | 分隔符號，特別是如果正規表示式包含 | 字元。

required

驗證的欄位必須存在於輸入資料中且不為空。如果符合以下條件之一，則欄位為「空」：

值為 null。
值為空字串。
值為空陣列或空的 Countable 物件。
值為沒有路徑的已上傳檔案。

required_if:anotherfield,value,...

如果 anotherfield 欄位等於任何 value，則驗證的欄位必須存在且不為空。

如果你想為 required_if 規則建構更複雜的條件，你可以使用 Rule::requiredIf 方法。此方法接受布林值或閉包。當傳遞閉包時，閉包應回傳 true 或 false 以指示驗證的欄位是否為必填：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($request->all(), [
    'role_id' => Rule::requiredIf($request->user()->is_admin),
]);

Validator::make($request->all(), [
    'role_id' => Rule::requiredIf(fn () => $request->user()->is_admin),
]);

required_if_accepted:anotherfield,...

如果 anotherfield 欄位等於 "yes"、"on"、1、"1"、true 或 "true"，則驗證的欄位必須存在且不為空。

required_if_declined:anotherfield,...

如果 anotherfield 欄位等於 "no"、"off"、0、"0"、false 或 "false"，則驗證的欄位必須存在且不為空。

required_unless:anotherfield,value,...

除非 anotherfield 欄位等於任何 value，否則驗證的欄位必須存在且不為空。這也表示 anotherfield 必須存在於請求資料中，除非 value 為 null。如果 value 為 null (required_unless:name,null)，則除非比較欄位為 null 或請求資料中缺少比較欄位，否則驗證的欄位將為必填。

required_with:foo,bar,...

僅當任何其他指定欄位存在且不為空時，驗證的欄位才必須存在且不為空。

required_with_all:foo,bar,...

僅當所有其他指定欄位都存在且不為空時，驗證的欄位才必須存在且不為空。

required_without:foo,bar,...

僅當任何其他指定欄位為空或不存在時，驗證的欄位才必須存在且不為空。

required_without_all:foo,bar,...

僅當所有其他指定欄位為空或不存在時，驗證的欄位才必須存在且不為空。

required_array_keys:foo,bar,...

驗證的欄位必須是一個陣列，並且必須包含至少指定的鍵。

same:field

給定的 field 必須與驗證的欄位相符。

size:value

驗證的欄位的大小必須與給定的 value 相符。對於字串資料，value 對應於字元數。對於數值資料，value 對應於給定的整數值（該屬性也必須具有 numeric 或 integer 規則）。對於陣列，size 對應於陣列的 count。對於檔案，size 對應於檔案大小（以 KB 為單位）。讓我們看一些範例：

// Validate that a string is exactly 12 characters long...
'title' => 'size:12';

// Validate that a provided integer equals 10...
'seats' => 'integer|size:10';

// Validate that an array has exactly 5 elements...
'tags' => 'array|size:5';

// Validate that an uploaded file is exactly 512 kilobytes...
'image' => 'file|size:512';

starts_with:foo,bar,...

驗證的欄位必須以給定值之一開頭。

string

驗證的欄位必須是字串。如果你想允許該欄位也為 null，則應將 nullable 規則分配給該欄位。

timezone

驗證的欄位必須是根據 DateTimeZone::listIdentifiers 方法的有效時區識別碼。

由 DateTimeZone::listIdentifiers 方法接受的參數也可以提供給此驗證規則：

'timezone' => 'required|timezone:all';

'timezone' => 'required|timezone:Africa';

'timezone' => 'required|timezone:per_country,US';

unique:table,column

驗證的欄位不得存在於給定的資料庫資料表中。

指定自訂資料表 / 欄位名稱：

你可以指定應使用哪個 Eloquent 模型來確定資料表名稱，而不是直接指定資料表名稱：

'email' => 'unique:App\Models\User,email_address'

column 選項可用於指定欄位對應的資料庫欄位。如果未指定 column 選項，將使用驗證欄位的名稱。

'email' => 'unique:users,email_address'

指定自訂資料庫連線

偶爾，你可能需要為驗證器執行的資料庫查詢設定自訂連線。為此，你可以在資料表名稱前加上連線名稱：

'email' => 'unique:connection.users,email_address'

強制唯一規則忽略給定 ID：

有時，你可能希望在唯一性驗證期間忽略給定 ID。例如，考慮一個包含使用者姓名、電子郵件地址和位置的「更新個人資料」畫面。你可能希望驗證電子郵件地址是唯一的。但是，如果使用者只更改姓名欄位而不是電子郵件欄位，你就不希望因為使用者已經是該電子郵件地址的擁有者而拋出驗證錯誤。

為了指示驗證器忽略使用者的 ID，我們將使用 Rule 類別流暢地定義規則。在此範例中，我們還將驗證規則指定為陣列，而不是使用 | 字元來分隔規則：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

Validator::make($data, [
    'email' => [
        'required',
        Rule::unique('users')->ignore($user->id),
    ],
]);

[!WARNING] 你絕不應將任何使用者控制的請求輸入傳遞給 ignore 方法。相反，你應該只傳遞系統生成的唯一 ID，例如 Eloquent 模型實例的自動遞增 ID 或 UUID。否則，你的應用程式將容易受到 SQL 注入攻擊。

你可以傳遞整個模型實例，而不是將模型鍵的值傳遞給 ignore 方法。Laravel 將自動從模型中提取鍵：

Rule::unique('users')->ignore($user)

如果你的資料表使用 id 以外的主鍵欄位名稱，你可以在呼叫 ignore 方法時指定欄位名稱：

Rule::unique('users')->ignore($user->id, 'user_id')

預設情況下，unique 規則將檢查與正在驗證的屬性名稱相符的欄位的唯一性。但是，你可以將不同的欄位名稱作為第二個參數傳遞給 unique 方法：

Rule::unique('users', 'email_address')->ignore($user->id)

新增額外的 Where 子句：

你可以透過使用 where 方法自訂查詢來指定額外的查詢條件。例如，讓我們新增一個查詢條件，將查詢範圍限定為僅搜尋 account_id 欄位值為 1 的記錄：

'email' => Rule::unique('users')->where(fn (Builder $query) => $query->where('account_id', 1))

在唯一性檢查中忽略軟刪除的記錄：

預設情況下，唯一性規則在確定唯一性時會包含軟刪除的記錄。要從唯一性檢查中排除軟刪除的記錄，你可以呼叫 withoutTrashed 方法：

Rule::unique('users')->withoutTrashed();

如果你的模型使用 deleted_at 以外的欄位名稱來表示軟刪除的記錄，你可以在呼叫 withoutTrashed 方法時提供欄位名稱：

Rule::unique('users')->withoutTrashed('was_deleted_at');

uppercase

驗證的欄位必須是大寫。

url

驗證的欄位必須是有效的 URL。

如果你想指定應被視為有效的 URL 協定，你可以將協定作為驗證規則參數傳遞：

'url' => 'url:http,https',

'game' => 'url:minecraft,steam',

ulid

驗證的欄位必須是有效的通用唯一詞典排序識別碼 (ULID)。

uuid

驗證的欄位必須是有效的 RFC 9562（版本 1、3、4、5、6、7 或 8）通用唯一識別碼 (UUID)。

你也可以透過版本驗證給定的 UUID 是否符合 UUID 規範：

'uuid' => 'uuid:4'

有條件地新增規則 (Conditionally Adding Rules)

當欄位具有特定值時跳過驗證 (Skipping Validation When Fields Have Certain Values)

你可能偶爾希望在另一個欄位具有給定值時不驗證給定欄位。你可以使用 exclude_if 驗證規則來實現此目的。在此範例中，如果 has_appointment 欄位的值為 false，則 appointment_date 和 doctor_name 欄位將不會被驗證：

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($data, [
    'has_appointment' => 'required|boolean',
    'appointment_date' => 'exclude_if:has_appointment,false|required|date',
    'doctor_name' => 'exclude_if:has_appointment,false|required|string',
]);

或者，你可以使用 exclude_unless 規則，除非另一個欄位具有給定值，否則不驗證給定欄位：

$validator = Validator::make($data, [
    'has_appointment' => 'required|boolean',
    'appointment_date' => 'exclude_unless:has_appointment,true|required|date',
    'doctor_name' => 'exclude_unless:has_appointment,true|required|string',
]);

存在時驗證 (Validating When Present)

在某些情況下，你可能希望僅當欄位存在於正在驗證的資料中時才對其執行驗證檢查。為了快速實現此目的，請將 sometimes 規則新增到你的規則列表中：

$validator = Validator::make($data, [
    'email' => 'sometimes|required|email',
]);

在上面的範例中，email 欄位僅在 $data 陣列中存在時才會被驗證。

[!NOTE] 如果你嘗試驗證一個應該始終存在但可能為空的欄位，請查看關於可選欄位的注意事項。

複雜的條件驗證 (Complex Conditional Validation)

有時你可能希望根據更複雜的條件邏輯新增驗證規則。例如，你可能希望僅當另一個欄位的值大於 100 時才要求給定欄位。或者，你可能需要兩個欄位僅在另一個欄位存在時才具有給定值。新增這些驗證規則不必很麻煩。首先，使用你的 靜態規則 建立一個 Validator 實例，這些規則永不改變：

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($request->all(), [
    'email' => 'required|email',
    'games' => 'required|integer|min:0',
]);

假設我們的網路應用程式是為遊戲收藏家設計的。如果遊戲收藏家註冊我們的應用程式並且他們擁有超過 100 款遊戲，我們希望他們解釋為什麼他們擁有這麼多遊戲。例如，他們可能經營一家遊戲轉售店，或者他們只是喜歡收集遊戲。為了有條件地新增此要求，我們可以在 Validator 實例上使用 sometimes 方法。

use Illuminate\Support\Fluent;

$validator->sometimes('reason', 'required|max:500', function (Fluent $input) {
    return $input->games >= 100;
});

傳遞給 sometimes 方法的第一個參數是我們有條件地驗證的欄位名稱。第二個參數是我們想要新增的規則列表。如果作為第三個參數傳遞的閉包回傳 true，則將新增規則。此方法使建構複雜的條件驗證變得輕而易舉。你甚至可以一次為多個欄位新增條件驗證：

$validator->sometimes(['reason', 'cost'], 'required', function (Fluent $input) {
    return $input->games >= 100;
});

[!NOTE] 傳遞給閉包的 $input 參數將是 Illuminate\Support\Fluent 的實例，可用於存取你的輸入和正在驗證的檔案。

複雜的條件陣列驗證 (Complex Conditional Array Validation)

有時你可能希望根據同一巢狀陣列中另一個欄位的值來驗證欄位，而你不知道該欄位的索引。在這些情況下，你可以允許你的閉包接收第二個參數，該參數將是正在驗證的陣列中的當前個別項目：

$input = [
    'channels' => [
        [
            'type' => 'email',
            'address' => 'abigail@example.com',
        ],
        [
            'type' => 'url',
            'address' => 'https://example.com',
        ],
    ],
];

$validator->sometimes('channels.*.address', 'email', function (Fluent $input, Fluent $item) {
    return $item->type === 'email';
});

$validator->sometimes('channels.*.address', 'url', function (Fluent $input, Fluent $item) {
    return $item->type !== 'email';
});

與傳遞給閉包的 $input 參數一樣，當屬性資料是陣列時，$item 參數是 Illuminate\Support\Fluent 的實例；否則，它是一個字串。

驗證陣列 (Validating Arrays)

如陣列驗證規則文件中所述，array 規則接受允許的陣列鍵列表。如果陣列中存在任何額外的鍵，驗證將失敗：

use Illuminate\Support\Facades\Validator;

$input = [
    'user' => [
        'name' => 'Taylor Otwell',
        'username' => 'taylorotwell',
        'admin' => true,
    ],
];

Validator::make($input, [
    'user' => 'array:name,username',
]);

通常，你應該始終指定允許存在於陣列中的陣列鍵。否則，驗證器的 validate 和 validated 方法將回傳所有已驗證的資料，包括陣列及其所有鍵，即使這些鍵未被其他巢狀陣列驗證規則驗證。

驗證巢狀陣列輸入 (Validating Nested Array Input)

驗證巢狀陣列式表單輸入欄位不必很麻煩。你可以使用「點符號」來驗證陣列中的屬性。例如，如果傳入的 HTTP 請求包含 photos[profile] 欄位，你可以這樣驗證它：

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($request->all(), [
    'photos.profile' => 'required|image',
]);

你也可以驗證陣列的每個元素。例如，要驗證給定陣列輸入欄位中的每個電子郵件都是唯一的，你可以執行以下操作：

$validator = Validator::make($request->all(), [
    'users.*.email' => 'email|unique:users',
    'users.*.first_name' => 'required_with:users.*.last_name',
]);

同樣，你可以在指定語言檔案中的自訂驗證訊息時使用 * 字元，這使得為基於陣列的欄位使用單一驗證訊息變得輕而易舉：

'custom' => [
    'users.*.email' => [
        'unique' => 'Each user must have a unique email address',
    ]
],

存取巢狀陣列資料 (Accessing Nested Array Data)

有時你可能需要在將驗證規則分配給屬性時存取給定巢狀陣列元素的值。你可以使用 Rule::forEach 方法來實現此目的。forEach 方法接受一個閉包，該閉包將針對正在驗證的陣列屬性的每次迭代呼叫，並將接收屬性的值和明確的、完全展開的屬性名稱。閉包應回傳要分配給陣列元素的規則陣列：

use App\Rules\HasPermission;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;

$validator = Validator::make($request->all(), [
    'companies.*.id' => Rule::forEach(function (string|null $value, string $attribute) {
        return [
            Rule::exists(Company::class, 'id'),
            new HasPermission('manage-company', $value),
        ];
    }),
]);

錯誤訊息索引和位置 (Error Message Indexes And Positions)

驗證陣列時，你可能希望在應用程式顯示的錯誤訊息中引用驗證失敗的特定項目的索引或位置。為此，你可以在自訂驗證訊息中包含 :index（從 0 開始）、:position（從 1 開始）或 :ordinal-position（從 1st 開始）佔位符：

use Illuminate\Support\Facades\Validator;

$input = [
    'photos' => [
        [
            'name' => 'BeachVacation.jpg',
            'description' => 'A photo of my beach vacation!',
        ],
        [
            'name' => 'GrandCanyon.jpg',
            'description' => '',
        ],
    ],
];

Validator::validate($input, [
    'photos.*.description' => 'required',
], [
    'photos.*.description.required' => 'Please describe photo #:position.',
]);

根據上面的範例，驗證將失敗，使用者將收到「請描述照片 #2。」的錯誤。

如有必要，你可以透過 second-index、second-position、third-index、third-position 等引用更深層次的巢狀索引和位置。

'photos.*.attributes.*.string' => 'Invalid attribute for photo #:second-position.',

驗證檔案 (Validating Files)

Laravel 提供了各種可用於驗證上傳檔案的驗證規則，例如 mimes、image、min 和 max。雖然你可以自由地在驗證檔案時單獨指定這些規則，但 Laravel 也提供了一個流暢的檔案驗證規則建構器，你可能會覺得很方便：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rules\File;

Validator::validate($input, [
    'attachment' => [
        'required',
        File::types(['mp3', 'wav'])
            ->min(1024)
            ->max(12 * 1024),
    ],
]);

驗證檔案類型 (Validating Files File Types)

即使你只需要在呼叫 types 方法時指定副檔名，此方法實際上也會透過讀取檔案內容並猜測其 MIME 類型來驗證檔案的 MIME 類型。MIME 類型及其對應副檔名的完整列表可在以下位置找到：

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

為了方便起見，最小和最大檔案大小可以指定為帶有指示檔案大小單位的後綴的字串。支援 kb、mb、gb 和 tb 後綴：

File::types(['mp3', 'wav'])
    ->min('1kb')
    ->max('10mb');

驗證圖片檔案 (Validating Files Image Files)

如果你的應用程式接受使用者上傳的圖片，你可以使用 File 規則的 image 建構函式方法來確保正在驗證的檔案是圖片（jpg、jpeg、png、bmp、gif 或 webp）。

此外，dimensions 規則可用於限制圖片的尺寸：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use Illuminate\Validation\Rules\File;

Validator::validate($input, [
    'photo' => [
        'required',
        File::image()
            ->min(1024)
            ->max(12 * 1024)
            ->dimensions(Rule::dimensions()->maxWidth(1000)->maxHeight(500)),
    ],
]);

[!NOTE] 有關驗證圖片尺寸的更多資訊，請參閱 dimensions 規則文件。

[!WARNING] 預設情況下，image 規則不允許 SVG 檔案，因為存在 XSS 漏洞的可能性。如果你需要允許 SVG 檔案，你可以將 allowSvg: true 傳遞給 image 規則：File::image(allowSvg: true)。

驗證圖片尺寸 (Validating Files Image Dimensions)

你也可以驗證圖片的尺寸。例如，要驗證上傳的圖片寬度至少為 1000 像素，高度至少為 500 像素，你可以使用 dimensions 規則：

use Illuminate\Validation\Rule;
use Illuminate\Validation\Rules\File;

File::image()->dimensions(
    Rule::dimensions()
        ->maxWidth(1000)
        ->maxHeight(500)
)

[!NOTE] 有關驗證圖片尺寸的更多資訊，請參閱 dimensions 規則文件。

驗證密碼 (Validating Passwords)

為了確保密碼具有足夠的複雜度，你可以使用 Laravel 的 Password 規則物件：

use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rules\Password;

$validator = Validator::make($request->all(), [
    'password' => ['required', 'confirmed', Password::min(8)],
]);

Password 規則物件允許你輕鬆自訂應用程式的密碼複雜度要求，例如指定密碼需要至少一個字母、數字、符號或大小寫混合的字元：

// Require at least 8 characters...
Password::min(8)

// Require at least one letter...
Password::min(8)->letters()

// Require at least one uppercase and one lowercase letter...
Password::min(8)->mixedCase()

// Require at least one number...
Password::min(8)->numbers()

// Require at least one symbol...
Password::min(8)->symbols()

此外，你可以使用 uncompromised 方法確保密碼未在公開密碼資料洩露中洩露：

Password::min(8)->uncompromised()

在內部，Password 規則物件使用 k-Anonymity 模型來判斷密碼是否透過 haveibeenpwned.com 服務洩露，而不會犧牲使用者的隱私或安全性。

預設情況下，如果密碼在資料洩露中至少出現一次，則將被視為已洩露。你可以使用 uncompromised 方法的第一個參數自訂此閾值：

// Ensure the password appears less than 3 times in the same data leak...
Password::min(8)->uncompromised(3);

當然，你可以鏈接上面範例中的所有方法：

Password::min(8)
    ->letters()
    ->mixedCase()
    ->numbers()
    ->symbols()
    ->uncompromised()

定義預設密碼規則 (Defining Default Password Rules)

你可能會發現在應用程式的單一位置指定密碼的預設驗證規則很方便。你可以使用 Password::defaults 方法輕鬆實現此目的，該方法接受一個閉包。提供給 defaults 方法的閉包應回傳密碼規則的預設配置。通常，defaults 規則應在應用程式的服務提供者之一的 boot 方法中呼叫：

use Illuminate\Validation\Rules\Password;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Password::defaults(function () {
        $rule = Password::min(8);

        return $this->app->isProduction()
            ? $rule->mixedCase()->uncompromised()
            : $rule;
    });
}

然後，當你希望將預設規則應用於正在驗證的特定密碼時，你可以不帶參數呼叫 defaults 方法：

'password' => ['required', Password::defaults()],

偶爾，你可能希望將額外的驗證規則附加到你的預設密碼驗證規則。你可以使用 rules 方法來實現此目的：

use App\Rules\ZxcvbnRule;

Password::defaults(function () {
    $rule = Password::min(8)->rules([new ZxcvbnRule]);

    // ...
});

自訂驗證規則 (Custom Validation Rules)

使用規則物件 (Using Rule Objects)

Laravel 提供了各種有用的驗證規則；但是，你可能希望指定一些自己的規則。註冊自訂驗證規則的一種方法是使用規則物件。要產生一個新的規則物件，你可以使用 make:rule Artisan 命令。讓我們使用此命令來產生一個驗證字串為大寫的規則。Laravel 會將新規則放置在 app/Rules 目錄中。如果此目錄不存在，Laravel 會在你執行 Artisan 命令建立規則時建立它：

php artisan make:rule Uppercase

一旦規則建立完成，我們就可以定義其行為。規則物件包含一個方法：validate。此方法接收屬性名稱、其值，以及一個在驗證失敗時應呼叫的回呼函式，並帶有驗證錯誤訊息：

<?php

namespace App\Rules;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class Uppercase implements ValidationRule
{
    /**
     * Run the validation rule.
     */
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (strtoupper($value) !== $value) {
            $fail('驗證的欄位必須是大寫。');
        }
    }
}

一旦規則定義完成，你可以透過將規則物件的實例與你的其他驗證規則一起傳遞給驗證器：

use App\Rules\Uppercase;

$request->validate([
    'name' => ['required', 'string', new Uppercase],
]);

翻譯驗證訊息

你可以提供翻譯字串鍵而不是向 $fail 閉包提供文字錯誤訊息，並指示 Laravel 翻譯錯誤訊息：

if (strtoupper($value) !== $value) {
    $fail('validation.uppercase')->translate();
}

如有必要，你可以將佔位符替換和首選語言作為 translate 方法的第一個和第二個參數提供：

$fail('validation.location')->translate([
    'value' => $this->value,
], 'fr');

存取額外資料

如果你的自訂驗證規則類別需要存取所有正在驗證的其他資料，你的規則類別可以實作 Illuminate\Contracts\Validation\DataAwareRule 介面。此介面要求你的類別定義一個 setData 方法。此方法將由 Laravel 自動呼叫（在驗證進行之前），並帶有所有正在驗證的資料：

<?php

namespace App\Rules;

use Illuminate\Contracts\Validation\DataAwareRule;
use Illuminate\Contracts\Validation\ValidationRule;

class Uppercase implements DataAwareRule, ValidationRule
{
    /**
     * All of the data under validation.
     *
     * @var array<string, mixed>
     */
    protected $data = [];

    // ...

    /**
     * 設定正在驗證的資料。
     *
     * @param  array<string, mixed>  $data
     */
    public function setData(array $data): static
    {
        $this->data = $data;

        return $this;
    }
}

或者，如果你的驗證規則需要存取執行驗證的驗證器實例，你可以實作 ValidatorAwareRule 介面：

<?php

namespace App\Rules;

use Illuminate\Contracts\Validation\ValidationRule;
use Illuminate\Contracts\Validation\ValidatorAwareRule;
use Illuminate\Validation\Validator;

class Uppercase implements ValidationRule, ValidatorAwareRule
{
    /**
     * The validator instance.
     *
     * @var \Illuminate\Validation\Validator
     */
    protected $validator;

    // ...

    /**
     * Set the current validator.
     */
    public function setValidator(Validator $validator): static
    {
        $this->validator = $validator;

        return $this;
    }
}

使用閉包 (Using Closures)

如果你只需要在應用程式中一次使用自訂規則的功能，你可以使用閉包而不是規則物件。閉包接收屬性名稱、屬性值和一個 $fail 回呼，如果驗證失敗，則應呼叫該回呼：

use Illuminate\Support\Facades\Validator;
use Closure;

$validator = Validator::make($request->all(), [
    'title' => [
        'required',
        'max:255',
        function (string $attribute, mixed $value, Closure $fail) {
            if ($value === 'foo') {
                $fail("The {$attribute} is invalid.");
            }
        },
    ],
]);

隱式規則 (Implicit Rules)

預設情況下，當正在驗證的屬性不存在或包含空字串時，正常的驗證規則（包括自訂規則）不會執行。例如，unique 規則不會針對空字串執行：

use Illuminate\Support\Facades\Validator;

$rules = ['name' => 'unique:users,name'];

$input = ['name' => ''];

Validator::make($input, $rules)->passes(); // true

為了使自訂規則即使在屬性為空時也能執行，該規則必須暗示該屬性是必需的。要快速產生一個新的隱式規則物件，你可以使用帶有 --implicit 選項的 make:rule Artisan 命令：

php artisan make:rule Uppercase --implicit

[!WARNING] 「隱式」規則僅暗示該屬性是必需的。它是否實際使缺失或空的屬性無效取決於你。