電子郵件驗證

• 簡介
  • 模型準備
  • 資料庫準備
• 路由
  • 電子郵件驗證通知
  • 電子郵件驗證處理器
  • 重新傳送驗證電子郵件
  • 保護路由
• 自訂
• 事件

簡介

許多 Web 應用程式要求使用者在使用應用程式前驗證其電子郵件地址。Laravel 提供了方便的內建服務來傳送和驗證電子郵件驗證請求，而不是強迫您為每個建立的應用程式手動重新實作此功能。

[!NOTE] 想要快速開始？在全新的 Laravel 應用程式中安裝其中一個 Laravel 應用程式入門套件。入門套件將負責建立您的整個認證系統的腳手架，包括電子郵件驗證支援。

模型準備

開始之前，請確認您的 App\Models\User 模型實作了 Illuminate\Contracts\Auth\MustVerifyEmail 合約：

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable implements MustVerifyEmail
{
    use Notifiable;

    // ...
}

一旦此介面被加入到您的模型中，新註冊的使用者將自動收到包含電子郵件驗證連結的電子郵件。這是無縫發生的，因為 Laravel 自動為 Illuminate\Auth\Events\Registered 事件註冊了 Illuminate\Auth\Listeners\SendEmailVerificationNotification 監聽器。

如果您正在應用程式中手動實作註冊，而不是使用入門套件，您應該確保在使用者註冊成功後派發 Illuminate\Auth\Events\Registered 事件：

use Illuminate\Auth\Events\Registered;

event(new Registered($user));

資料庫準備

接下來，您的 users 資料表必須包含 email_verified_at 欄位，以儲存使用者電子郵件地址被驗證的日期和時間。通常，這已包含在 Laravel 預設的 0001_01_01_000000_create_users_table.php 資料庫遷移中。

路由

為了正確實作電子郵件驗證，需要定義三個路由。首先，需要一個路由來向使用者顯示通知，告知他們應點選 Laravel 在註冊後傳送的驗證電子郵件中的驗證連結。

其次，需要一個路由來處理使用者點選電子郵件中的驗證連結時產生的請求。

第三，需要一個路由，以便在使用者意外遺失第一個驗證連結時重新傳送驗證連結。

電子郵件驗證通知

如前所述，應定義一個路由，該路由將返回一個視圖，指示使用者點選 Laravel 在註冊後透過電子郵件傳送給他們的驗證連結。當使用者嘗試在未先驗證電子郵件地址的情況下存取應用程式的其他部分時，將向他們顯示此視圖。請記住，只要您的 App\Models\User 模型實作了 MustVerifyEmail 介面，該連結就會自動透過電子郵件傳送給使用者：

Route::get('/email/verify', function () {
    return view('auth.verify-email');
})->middleware('auth')->name('verification.notice');

返回電子郵件驗證通知的路由應命名為 verification.notice。重要的是該路由必須被賦予此確切名稱，因為 verified 中介層（Laravel 附含）將在使用者未驗證其電子郵件地址時自動重新導向到此路由名稱。

[!NOTE] 手動實作電子郵件驗證時，您需要自行定義驗證通知視圖的內容。如果您希望包含所有必要認證和驗證視圖的腳手架，請查看 Laravel 應用程式入門套件。

電子郵件驗證處理器

接下來，我們需要定義一個路由來處理使用者點選透過電子郵件傳送給他們的驗證連結時產生的請求。此路由應命名為 verification.verify，並分配 auth 和 signed 中介層：

use Illuminate\Foundation\Auth\EmailVerificationRequest;

Route::get('/email/verify/{id}/{hash}', function (EmailVerificationRequest $request) {
    $request->fulfill();

    return redirect('/home');
})->middleware(['auth', 'signed'])->name('verification.verify');

在繼續之前，讓我們仔細看看這個路由。首先，您會注意到我們使用 EmailVerificationRequest 請求類型，而不是典型的 Illuminate\Http\Request 實例。EmailVerificationRequest 是 Laravel 附含的表單請求。此請求將自動處理驗證請求的 id 和 hash 參數。

接下來，我們可以直接呼叫請求上的 fulfill 方法。此方法將在已認證的使用者上呼叫 markEmailAsVerified 方法，並派發 Illuminate\Auth\Events\Verified 事件。markEmailAsVerified 方法透過 Illuminate\Foundation\Auth\User 基礎類別對預設的 App\Models\User 模型可用。一旦使用者的電子郵件地址被驗證，您可以將其重新導向到任何您希望的位置。

重新傳送驗證電子郵件

有時候使用者可能會遺失或意外刪除電子郵件地址驗證電子郵件。為此，您可能希望定義一個路由，允許使用者請求重新傳送驗證電子郵件。然後，您可以在驗證通知視圖中放置一個簡單的表單提交按鈕來向此路由發出請求：

use Illuminate\Http\Request;

Route::post('/email/verification-notification', function (Request $request) {
    $request->user()->sendEmailVerificationNotification();

    return back()->with('message', 'Verification link sent!');
})->middleware(['auth', 'throttle:6,1'])->name('verification.send');

保護路由

路由中介層可用於僅允許已驗證的使用者存取給定路由。Laravel 包含一個 verified 中介層別名，它是 Illuminate\Auth\Middleware\EnsureEmailIsVerified 中介層類別的別名。由於此別名已被 Laravel 自動註冊，您只需將 verified 中介層附加到路由定義即可。通常，此中介層與 auth 中介層配對：

Route::get('/profile', function () {
    // Only verified users may access this route...
})->middleware(['auth', 'verified']);

如果未驗證的使用者嘗試存取已分配此中介層的路由，他們將被自動重新導向到 verification.notice 命名路由。

自訂

驗證電子郵件自訂

雖然預設的電子郵件驗證通知應滿足大多數應用程式的需求，但 Laravel 允許您自訂電子郵件驗證郵件訊息的建構方式。

要開始，請將閉包傳遞給 Illuminate\Auth\Notifications\VerifyEmail 通知提供的 toMailUsing 方法。閉包將接收接收通知的可通知模型實例，以及使用者必須訪問以驗證其電子郵件地址的已簽署電子郵件驗證 URL。閉包應返回 Illuminate\Notifications\Messages\MailMessage 的實例。通常，應從您應用程式的 AppServiceProvider 類別的 boot 方法中呼叫 toMailUsing 方法：

use Illuminate\Auth\Notifications\VerifyEmail;
use Illuminate\Notifications\Messages\MailMessage;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    // ...

    VerifyEmail::toMailUsing(function (object $notifiable, string $url) {
        return (new MailMessage)
            ->subject('Verify Email Address')
            ->line('Click the button below to verify your email address.')
            ->action('Verify Email Address', $url);
    });
}

[!NOTE] 如需了解更多關於郵件通知的資訊，請參閱郵件通知文件。

事件

使用 Laravel 應用程式入門套件時，Laravel 會在電子郵件驗證過程中派發 Illuminate\Auth\Events\Verified 事件。如果您正在為應用程式手動處理電子郵件驗證，您可能希望在驗證完成後手動派發這些事件。