重設密碼

• 簡介

  • Model 的準備
  • 資料庫的準備
  • 設定 Trusted Hosts

• 路由

  • Requesting the Password Reset Link
  • Resetting the Password

• 刪除過期的 Token

• 自定

簡介

大多數的 Web App 都提供了能讓使用者重設密碼的功能。在 Laravel 中，我們不需要為密碼重設重造輪子，Laravel 已提供了方便的服務，可讓我們傳送密碼重設連結並安全地重設密碼。

Model 的準備

在使用 Laravel 的密碼重設功能前，專案中的 App\Models\User Model 必須使用 Illuminate\Notifications\Notifiable Trait。一般來說，在 Laravel 新專案中，預設的 App\Models\User 內已包含了該 Trait。

接著，請確認一下 App\Models\User Model 是否有實作 Illuminate\Contracts\Auth\CanResetPassword Contract。Laravel 中包含的 App\Models\User Model 已經有實作該介面了，且這個 Model 還使用了 Illuminate\Auth\Passwords\CanResetPassword Trait 來提供實作該介面所需要的各個方法。

資料庫的準備

A table must be created to store your application's password reset tokens. Typically, this is included in Laravel's default 0001_01_01_000000_create_users_table.php database migration.

設定信任的主機 (Trusted Hosts)

預設情況下，無論收到的 HTTP Request 中 Host 標頭內容為何，Laravel 都會回應所有收到的 Request。此外，Laravel 還會使用 Host 標頭的值來在 Request 中產生絕對路徑的網址。

Typically, you should configure your web server, such as Nginx or Apache, to only send requests to your application that match a given hostname. However, if you do not have the ability to customize your web server directly and need to instruct Laravel to only respond to certain hostnames, you may do so by using the trustHosts middleware method in your application's bootstrap/app.php file. This is particularly important when your application offers password reset functionality.

To learn more about this middleware method, please consult the TrustHosts middleware documentation.

路由

若要正確實作讓使用者重設密碼的功能，我們需要定義多個 Route。首先，我們需要一組用來讓使用者通過 E-Mail 位址要求密碼重設連結的 Route。接著，我們需要定義一組 Route 來實際處理密碼重設功能，即，處理使用者點擊信件中的密碼重設連結後顯示與送出密碼重設表單的 Route。

Requesting the Password Reset Link

要求密碼重設連結的表單

首先，我們需要定義一個用來要求密碼重設連結的 Route。首先，我們先定義一個回傳 View 的 Route，該 View 即為要求密碼重設連結的表單：

1Route::get('/forgot-password', function () {
2    return view('auth.forgot-password');
3})->middleware('guest')->name('password.request');
1Route::get('/forgot-password', function () {
2    return view('auth.forgot-password');
3})->middleware('guest')->name('password.request');

該 Route 所回傳的 View 應包含一個 email 欄位，該欄位用來讓使用者可使用給定的 E-Mail 位址要求密碼重設連結。

Handling the Form Submission

接著，我們需要定義一個 Route 來處理「忘記密碼」View 送出的表單。這個 Route 會負責驗證 E-Mail 位址，並寄出密碼重設連結給對應的使用者：

 1use Illuminate\Http\Request;
 2use Illuminate\Support\Facades\Password;
 3 
 4Route::post('/forgot-password', function (Request $request) {
 5    $request->validate(['email' => 'required|email']);
 6 
 7    $status = Password::sendResetLink(
 8        $request->only('email')
 9    );
10 
11    return $status === Password::RESET_LINK_SENT
12                ? back()->with(['status' => __($status)])
13                : back()->withErrors(['email' => __($status)]);
14})->middleware('guest')->name('password.email');
 1use Illuminate\Http\Request;
 2use Illuminate\Support\Facades\Password;
 3 
 4Route::post('/forgot-password', function (Request $request) {
 5    $request->validate(['email' => 'required|email']);
 6 
 7    $status = Password::sendResetLink(
 8        $request->only('email')
 9    );
10 
11    return $status === Password::RESET_LINK_SENT
12                ? back()->with(['status' => __($status)])
13                : back()->withErrors(['email' => __($status)]);
14})->middleware('guest')->name('password.email');

在繼續之前，我們先來詳細看看這個 Route。首先，會先驗證 Request 的 email 屬性。接著，我們使用 Laravel 內建的「Password Broker」(在 Password Facade 上) 來傳送密碼重設連結給該使用者。Password Broker 會負責使用給定的欄位 (在這個例子中是 E-Mail 位址) 來取得使用者，並使用 Laravel 內建的通知系統來傳送密碼重設連結給使用者。

sendResetLink 方法會回傳一個「status」slug。我們可以使用 Laravel 的[本土化]輔助函式來翻譯這個「status」，以顯示使用者友善的訊息告知使用者其密碼要求狀態。密碼重設的翻譯會依據專案中的 lang/{lang}/passwords.php 語系檔來判斷。在 passwords 語系檔中，所有可能的 status slug 值都有對應的欄位。

讀者可能會想，在呼叫 Password Facade 的 sendResetLink 時，Laravel 是怎麼知道要如何從專案資料庫中取得使用者記錄的？其實，Laravel 的 Password Broker 使用了身份驗證系統的「User Providers」來取得資料庫記錄。Password Broker 使用的 User Provider 設定在 config/auth.php 設定檔中的 password 設定陣列中。如欲瞭解更多有關如何撰寫自定 User Provider 的資訊，請參考身份驗證說明文件。

Resetting the Password

密碼重設表單

接著，我們還需要定義一個 Route，能讓使用者在點擊信件中的密碼重設連結後能真的重設密碼。首先，我們先定義一個在使用者點擊密碼重設連結後顯示密碼重設表單的 Route。這個 Route 會收到一個 token 參數，我們在稍後會用來驗證這個密碼重設 Request。

1Route::get('/reset-password/{token}', function (string $token) {
2    return view('auth.reset-password', ['token' => $token]);
3})->middleware('guest')->name('password.reset');
1Route::get('/reset-password/{token}', function (string $token) {
2    return view('auth.reset-password', ['token' => $token]);
3})->middleware('guest')->name('password.reset');

該表單回傳的 View 應顯示一個表單，其中需包含 email、password、password_confirmation 等欄位，以及一個隱藏的 token 等欄位，該 token 欄位中應包含該 Route 所收到的私密 Token $token 值。

Handling the Form Submission

當然，我們還需要定義一個實際用來處理表單送出的 Route。這個 Route 要負責驗證連入的 Request，並更新資料庫中該使用者的密碼：

 1use App\Models\User;
 2use Illuminate\Auth\Events\PasswordReset;
 3use Illuminate\Http\Request;
 4use Illuminate\Support\Facades\Hash;
 5use Illuminate\Support\Facades\Password;
 6use Illuminate\Support\Str;
 7 
 8Route::post('/reset-password', function (Request $request) {
 9    $request->validate([
10        'token' => 'required',
11        'email' => 'required|email',
12        'password' => 'required|min:8|confirmed',
13    ]);
14 
15    $status = Password::reset(
16        $request->only('email', 'password', 'password_confirmation', 'token'),
17        function (User $user, string $password) {
18            $user->forceFill([
19                'password' => Hash::make($password)
20            ])->setRememberToken(Str::random(60));
21 
22            $user->save();
23 
24            event(new PasswordReset($user));
25        }
26    );
27 
28    return $status === Password::PASSWORD_RESET
29                ? redirect()->route('login')->with('status', __($status))
30                : back()->withErrors(['email' => [__($status)]]);
31})->middleware('guest')->name('password.update');
 1use App\Models\User;
 2use Illuminate\Auth\Events\PasswordReset;
 3use Illuminate\Http\Request;
 4use Illuminate\Support\Facades\Hash;
 5use Illuminate\Support\Facades\Password;
 6use Illuminate\Support\Str;
 7 
 8Route::post('/reset-password', function (Request $request) {
 9    $request->validate([
10        'token' => 'required',
11        'email' => 'required|email',
12        'password' => 'required|min:8|confirmed',
13    ]);
14 
15    $status = Password::reset(
16        $request->only('email', 'password', 'password_confirmation', 'token'),
17        function (User $user, string $password) {
18            $user->forceFill([
19                'password' => Hash::make($password)
20            ])->setRememberToken(Str::random(60));
21 
22            $user->save();
23 
24            event(new PasswordReset($user));
25        }
26    );
27 
28    return $status === Password::PASSWORD_RESET
29                ? redirect()->route('login')->with('status', __($status))
30                : back()->withErrors(['email' => [__($status)]]);
31})->middleware('guest')->name('password.update');

在繼續之前，我們先來仔細看看這個 Route。首先，在這個 Route 中會先驗證 Request 的 token、email、password 等欄位。接著，​我們 (通過 Password Facade) 使用 Laravel 內建的「Password Broker」來驗證密碼重設 Request 是否有效。

若傳給 Password Broker 的 Token、E-Mail 位址、密碼等均正確，則會呼叫傳給 reset 方法的閉包。這個閉包會收到 User 實體以及傳給密碼重設表單的明文密碼。在該閉包中，我們就可以更新資料庫中該使用者的密碼。

reset 方法會回傳一個「status」Slug。我們可以使用 Laravel 的本土化輔助函式來翻譯這個「status」，以顯示使用者友善的訊息告知使用者其密碼要求狀態。密碼重設的翻譯會依據專案中的 lang/{lang}/passwords.php 語系檔來判斷。在 passwords 語系檔中，所有可能的 status slug 值都有對應的欄位。如果你的專案中沒有 lang 目錄，可使用 lang:publish Artisan 指令來建立該目錄。

在繼續之前，讀者可能會想，在呼叫 Password Facade 的 reset 時，Laravel 是怎麼知道要如何從專案資料庫中取得使用者記錄的？其實，Laravel 的 Password Broker 使用了身份驗證系統的「User Providers」來取得資料庫記錄。Password Broker 使用的 User Provider 設定在 config/auth.php 設定檔中的 password 設定陣列中。如欲瞭解更多有關如何撰寫自定 User Provider 的資訊，請參考身份驗證說明文件。

刪除過期的 Token

過期的密碼重設連結會繼續保存在資料庫中。不過，我們可以使用 auth:clear-resets Artisan 指令來輕鬆刪除這些記錄：

1php artisan auth:clear-resets
1php artisan auth:clear-resets

若想自動化這個過程，可以考慮將該指令加入專案的排程任務中：

1use Illuminate\Support\Facades\Schedule;
2 
3Schedule::command('auth:clear-resets')->everyFifteenMinutes();
1use Illuminate\Support\Facades\Schedule;
2 
3Schedule::command('auth:clear-resets')->everyFifteenMinutes();

自定

自定重設連結

You may customize the password reset link URL using the createUrlUsing method provided by the ResetPassword notification class. This method accepts a closure which receives the user instance that is receiving the notification as well as the password reset link token. Typically, you should call this method from your App\Providers\AppServiceProvider service provider's boot method:

 1use App\Models\User;
 2use Illuminate\Auth\Notifications\ResetPassword;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    ResetPassword::createUrlUsing(function (User $user, string $token) {
10        return 'https://example.com/reset-password?token='.$token;
11    });
12}
 1use App\Models\User;
 2use Illuminate\Auth\Notifications\ResetPassword;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    ResetPassword::createUrlUsing(function (User $user, string $token) {
10        return 'https://example.com/reset-password?token='.$token;
11    });
12}

自定重設 E-Mail

我們也可以輕鬆調整用來傳送密碼重設連結給使用者的通知類別。若要自定該通知，請在 App\Models\User Model 中複寫 sendPasswordResetNotification 方法。在該方法中，我們可以使用任何一個自行建立的 Notification 類別來傳送通知。該方法的第一個引數是密碼重設連結的 $token。我們可以使用這個 $token 來建立我們自已的密碼重設連結並用來傳送通知給使用者：

 1use App\Notifications\ResetPasswordNotification;
 2 
 3/**
 4 * Send a password reset notification to the user.
 5 *
 6 * @param  string  $token
 7 */
 8public function sendPasswordResetNotification($token): void
 9{
10    $url = 'https://example.com/reset-password?token='.$token;
11 
12    $this->notify(new ResetPasswordNotification($url));
13}
 1use App\Notifications\ResetPasswordNotification;
 2 
 3/**
 4 * Send a password reset notification to the user.
 5 *
 6 * @param  string  $token
 7 */
 8public function sendPasswordResetNotification($token): void
 9{
10    $url = 'https://example.com/reset-password?token='.$token;
11 
12    $this->notify(new ResetPasswordNotification($url));
13}