邮箱验证

简介

许多 Web 应用要求用户在使用前验证邮箱地址。Laravel 提供了便捷的内置服务，用于发送与校验邮箱验证请求，而无需你在每个应用中亲手重写该功能。

INFO

想快速上手？在全新的 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。务必使用该精确名称，因为 Laravel 内置的 verified 中间件在用户尚未验证邮箱时，会自动重定向到该路由名称。

INFO

手动实现邮箱验证时，你需要自行定义验证提示视图的内容。若希望获得包含全部必要认证与验证视图的脚手架，请参阅 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 事件。默认 App\Models\User 模型通过 Illuminate\Foundation\Auth\User 基类即可使用 markEmailAsVerified。用户邮箱验证完成后，你可将他们重定向到任意位置。

重新发送验证邮件

有时用户可能遗失或不慎删除邮箱验证邮件。为此，你可以定义一条路由，允许用户请求重新发送验证邮件。然后可在验证提示视图中放置一个简单的表单提交按钮来请求该路由：

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);
    });
}

INFO

要进一步了解邮件通知，请参阅邮件通知文档。

事件

使用 Laravel 应用起步套件 时，Laravel 会在邮箱验证过程中派发 Illuminate\Auth\Events\Verified 事件。若你手动处理应用的邮箱验证，可在验证完成后自行派发这些事件。