Laravel Fortify 自定义密码创建流程中的令牌生成指南

在 Laravel Fortify 中实现自定义用户密码创建（如欢迎邮件）时，直接使用 Str::random() 生成的令牌无法通过验证。本文将指导您如何利用 Laravel 内置的 PasswordBroker 服务，生成与 Fortify 兼容且可用于密码重置或创建的有效令牌，确保自定义流程的安全性与功能性。

挑战：自定义密码创建与令牌验证

在许多应用场景中，我们可能需要自定义用户注册后的密码设置流程。例如，在用户首次注册时，不直接设置密码，而是向其发送一封包含链接的欢迎邮件，引导用户点击链接进入页面自行创建密码。这种“密码创建”流程与 laravel fortify 提供的“密码重置”流程在本质上是相似的，都需要一个安全的、有时效性的令牌来验证用户的身份。

然而，当开发者尝试手动生成令牌，例如使用 Str::random(60)，并将其发送给用户时，往往会发现该令牌无法通过 Laravel Fortify 或其底层 PasswordBroker 的验证。这是因为 Laravel 的密码重置/创建机制并非简单地验证随机字符串，它要求令牌必须通过特定的内部服务生成并存储，以便后续进行验证。

理解 Laravel 的 PasswordBroker 服务

Laravel 提供了一个强大的 PasswordBroker 服务，专门用于管理用户密码重置的整个生命周期。这个服务负责：

1. 生成令牌： 创建一个加密且具有时效性的令牌。
2. 存储令牌： 将生成的令牌与对应的用户ID和创建时间一同存储在数据库的 password_resets 表中。
3. 验证令牌： 在用户尝试重置密码时，根据数据库中的记录验证提供的令牌是否有效、是否过期。
4. 删除令牌： 密码重置成功后，删除对应的令牌，确保令牌一次性使用。

因此，如果我们需要在自定义流程中生成一个能被 Laravel 验证的令牌，就必须利用这个 PasswordBroker 服务。

正确生成兼容令牌的方法

要生成一个与 Laravel Fortify 兼容的令牌，我们需要从 Laravel 的服务容器中获取 PasswordBroker 实例，并调用其 createToken() 方法。该方法会为指定的用户生成一个有效的令牌，并自动将其存储在 password_resets 表中。

以下是在自定义用户创建流程中生成有效令牌的示例代码：

validated(),
                ['password' => bcrypt(Str::random(8))] // 初始设置一个随机密码，或者可以设置为 null
            )
        );

        // 2. 使用 PasswordBroker 服务生成令牌
        // 从服务容器中获取 PasswordBroker 实例
        $passwordBroker = app(PasswordBroker::class);
        // 为指定用户生成令牌，并自动存储到 password_resets 表
        $token = $passwordBroker->createToken($user);

        // 3. 发送包含令牌的密码创建通知邮件
        // 假设您已经定义了 sendPasswordCreateNotification 方法
        // 并且该方法接受一个令牌作为参数，用于构建密码设置链接
        $user->sendPasswordCreateNotification($token);

        // 返回重定向或其他响应
        return redirect()->route('users.index')->with('success', '用户已创建，密码设置邮件已发送！');
    }
}

代码解析：

1. app(PasswordBroker::class): 这是 Laravel 服务容器的辅助函数，用于解析并获取 Illuminate\Auth\Passwords\PasswordBroker 类的实例。
2. $passwordBroker->createToken($user): 调用 PasswordBroker 实例的 createToken() 方法，并传入 User 模型实例。此方法会执行以下操作：
   • 生成一个加密的安全令牌。
   • 将该令牌、用户 ID (user_id) 和创建时间 (created_at) 存储到 password_resets 数据库表中。
   • 返回生成的令牌字符串。

通过这种方式获取的 $token 是一个有效的、与 Laravel 密码重置机制完全兼容的令牌。当用户点击邮件中的链接，访问到您的密码设置页面时，您可以使用 Fortify 提供的密码重置视图和逻辑，或者自定义控制器来验证这个令牌。

邮件通知与路由配置

在上述示例中，我们假设 sendPasswordCreateNotification($token) 方法已经存在。您需要确保您的用户模型包含类似以下的方法，并且您的通知类（例如 PasswordCreateNotification）能够构建包含此令牌的 URL。

User 模型中的通知方法示例：

// app/Models/User.php

use App\Notifications\PasswordCreateNotification; // 引入您的通知类

class User extends Authenticatable
{
    // ... 其他属性和方法

    /**
     * 发送密码创建通知。
     *
     * @param string $token
     * @return void
     */
    public function sendPasswordCreateNotification(string $token): void
    {
        $this->notify(new PasswordCreateNotification($token));
    }
}

通知类 (PasswordCreateNotification) 示例：

// app/Notifications/PasswordCreateNotification.php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;

class PasswordCreateNotification extends Notification
{
    use Queueable;

    public string $token;

    /**
     * 创建一个新的通知实例。
     *
     * @param string $token
     * @return void
     */
    public function __construct(string $token)
    {
        $this->token = $token;
    }

    /**
     * 获取通知的交付渠道。
     *
     * @param mixed $notifiable
     * @return array
     */
    public function via(mixed $notifiable): array
    {
        return ['mail'];
    }

    /**
     * 获取邮件表示形式的通知。
     *
     * @param mixed $notifiable
     * @return MailMessage
     */
    public function toMail(mixed $notifiable): MailMessage
    {
        // 构建密码设置链接
        // 假设您的密码设置路由是 'password.create.form'，并且接受 token 和 email 参数
        $url = url(route('password.create.form', [
            'token' => $this->token,
            'email' => $notifiable->getEmailForPasswordReset(),
        ], false)); // false 表示生成相对 URL，如果需要绝对 URL，请根据实际情况调整

        return (new MailMessage)
                    ->subject('请设置您的账户密码')
                    ->line('您好，请点击下方链接为您的账户设置密码：')
                    ->action('设置密码', $url)
                    ->line('如果您没有请求此操作，请忽略此邮件。');
    }
}

路由配置示例 (web.php):

// routes/web.php

use App\Http\Controllers\Auth\NewPasswordController; // 假设您自定义了控制器

// 自定义密码创建路由，用于展示密码设置表单
Route::get('/create-password/{token}', [NewPasswordController::class, 'create'])
    ->name('password.create.form');

// 处理密码创建提交
Route::post('/create-password', [NewPasswordController::class, 'store'])
    ->name('password.create.store');

在 NewPasswordController 中，您可以使用与 Fortify 密码重置控制器类似的逻辑来验证令牌并更新用户密码。

注意事项

• 数据库迁移： 确保您的数据库中存在 password_resets 表。Laravel 默认提供了此迁移文件 (xxxx_create_password_resets_table.php)，如果尚未运行，请执行 php artisan migrate。
• 令牌有效期： PasswordBroker 生成的令牌通常具有默认的有效期（默认为 60 分钟），您可以在 config/auth.php 文件中调整 passwords.users.expire 配置项。
• 安全性： 令牌是一次性使用的。一旦用户成功设置了密码，对应的令牌应立即从 password_resets 表中删除。Laravel 的 PasswordBroker 在密码重置成功后会自动处理这一点。
• 错误处理： 在处理用户提交的密码设置请求时，务必对令牌进行严格验证，并提供友好的错误提示。

总结

在 Laravel Fortify 中实现自定义的用户密码创建流程时，关键在于正确生成和管理令牌。直接使用 Str::random() 生成的令牌无法被 Laravel 的内置验证机制识别。通过利用 Illuminate\Auth\Passwords\PasswordBroker 服务，我们可以生成一个与 Fortify 完全兼容的有效令牌，并将其安全地发送给用户。这种方法不仅保证了流程的安全性，也充分利用了 Laravel 提供的强大认证功能，确保了自定义功能的稳定性和可靠性。

以上就是Laravel Fortify 自定义密码创建流程中的令牌生成指南的详细内容，更多请关注启程网【www.kunjuke.com】。