邮件验证

简介

很多 Web 应用都要求用户在使用应用之前先验证邮箱地址。与其让你在每个应用里都手动实现这套功能，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。这个名字必须一字不差，因为 Laravel 内置的 verified 中间件会在用户未验证邮箱时自动重定向到这个命名路由。

邮件验证处理器

接下来，我们需要定义一条路由，处理用户点击邮件中验证链接后产生的请求。这条路由应该命名为 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 内置的一个表单请求（Form Request），它会自动校验请求的 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 () {
    // 只有验证过邮箱的用户才能访问这条路由...
})->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);
    });
}

事件

当使用 Laravel 应用起步套件时，Laravel 会在邮件验证过程中派发一个 Illuminate\Auth\Events\Verified 事件。如果你在应用中手动处理邮件验证，可能需要在验证完成后手动派发这些事件。