Skip to content

Commit 42a5558

Browse files
taylorotwelltaylorotwell
committed
manual password reset documentation
1 parent fca9f71 commit 42a5558

File tree

2 files changed

+104
-20
lines changed

2 files changed

+104
-20
lines changed

‎passwords.md‎

Lines changed: 101 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,126 @@
11
# Resetting Passwords
22

33
- [Introduction](#introduction)
4-
- [Database Considerations](#resetting-database)
5-
- [Routing](#resetting-routing)
6-
- [Views](#resetting-views)
4+
- [Model Preparation](#model-preparation)
5+
- [Database Preparation](#database-preparation)
6+
- [Routing](#routing)
7+
- [Requesting The Password Reset Link](#requesting-the-password-reset-link)
8+
- [Resetting The Password](#resetting-the-password)
79
- [Customization](#password-customization)
810

911
<a name="introduction"></a>
1012
## Introduction
1113

1214
Most web applications provide a way for users to reset their forgotten passwords. Rather than forcing you to re-implement this on each application, Laravel provides convenient methods for sending password reminders and performing password resets.
1315

14-
> {note} Before using the password reset features of Laravel, your user must use the `Illuminate\Notifications\Notifiable` trait.
16+
> {tip} Want to get started fast? Install [Laravel Jetstream](https://jetstream.laravel.com) in a fresh Laravel application. After migrating your database, navigate your browser to `/register` or any other URL that is assigned to your application. Jetstream will take care of scaffolding your entire authentication system, including resetting passwords!
1517
16-
#### Getting Started Fast
18+
<a name="model-preparation"></a>
19+
### Model Preparation
1720

18-
Want to get started fast? Install [Laravel Jetstream](https://jetstream.laravel.com) in a fresh Laravel application. After migrating your database, navigate your browser to `/register` or any other URL that is assigned to your application. Jetstream will take care of scaffolding your entire authentication system, including resetting passwords!
21+
Before using the password reset features of Laravel, your user must use the `Illuminate\Notifications\Notifiable` trait. Typically, this trait is automatically included on the default `App\Models\User` model that is included with Laravel.
1922

20-
<a name="resetting-database"></a>
21-
## Database Considerations
23+
Next, verify that your `App\Models\User` model implements the `Illuminate\Contracts\Auth\CanResetPassword` contract. The `App\Models\User` model included with the framework already implements this interface, and uses the `Illuminate\Auth\Passwords\CanResetPassword` trait to include the methods needed to implement the interface.
2224

23-
To get started, verify that your `App\Models\User` model implements the `Illuminate\Contracts\Auth\CanResetPassword` contract. The `App\Models\User` model included with the framework already implements this interface, and uses the `Illuminate\Auth\Passwords\CanResetPassword` trait to include the methods needed to implement the interface.
25+
<a name="database-preparation"></a>
26+
### Database Preparation
2427

25-
#### Generating The Reset Token Table Migration
26-
27-
Next, a table must be created to store the password reset tokens. The migration for this table is included in the default Laravel installation, so you only need to migrate your database to create this table:
28+
A table must be created to store the password reset tokens. The migration for this table is included in the default Laravel installation, so you only need to migrate your database to create this table:
2829

2930
php artisan migrate
3031

31-
<a name="resetting-routing"></a>
32+
<a name="routing"></a>
3233
## Routing
3334

34-
All of the routes needed to perform password resets are automatically included in [Laravel Jetstream](https://jetstream.laravel.com). To learn how to install Jetstream, please consult the official [Jetstream documentation](https://jetstream.laravel.com).
35+
To properly implement support for allowing users to reset their passwords, we will need to define several routes. First, we will need a pair of routes to handle allowing the user to request a password reset link via their email address. Second, we will need a pair of routes to handle actually resetting the password once the user visits the password reset link that is emailed to them.
36+
37+
<a name="requesting-the-password-reset-link"></a>
38+
### Requesting The Password Reset Link
39+
40+
First, we will define the routes that are needed to request password reset links. To get started, we will define a route that returns a view with the password reset link request form:
41+
42+
Route::get('/forgot-password', function () {
43+
return view('auth.forgot-password');
44+
})->middleware(['guest'])->name('password.request');
45+
46+
The view that is returned by this route should have an `email` field within its form, which will allow the user to request a password reset link for a given email address.
47+
48+
Next, we will define a route will handle the form request from the "forgot password" view. This route will be responsible for validating the email address and sending the password reset request to the corresponding user:
49+
50+
use Illuminate\Http\Request;
51+
use Illuminate\Support\Facades\Password;
52+
53+
Route::post('/forgot-password', function (Request $request) {
54+
$request->validate(['email' => 'required|email']);
55+
56+
$status = Password::sendResetLink(
57+
$request->only('email')
58+
);
59+
60+
return $status === Password::RESET_LINK_SENT
61+
? back()->with(['status' => trans($status)])
62+
: back()->withErrors(['email' => trans($status)]);
63+
})->middleware(['guest'])->name('password.email');
64+
65+
Before moving on, let's examine this route in more detail. First, the request's `email` attribute is validated. Next, we will use Laravel's built-in "password broker" to send a password reset link to the user. The password broker will take care of retrieving the user by the given field (in this case, the email address) and sending the user a password reset link via Laravel's built-in [notification system](/docs/{{version}}/notifications).
66+
67+
The `sendResetLink` method returns a "status" slug. This status may be translated using Laravel's [localization](/docs/{{version}}/localization) helpers in order to display a user-friendly message to the user regarding the status of their request. The translation of the password reset status is determined by your application's `resources/lang/{lang}/password.php` language file.
68+
69+
> {tip} When manually implementing password resets, you are required to define the contents of the the views yourself. If you would like scaffolding that includes all necessary authentication and verification views, check out [Laravel Jetstream](https://jetstream.laravel.com).
70+
71+
<a name="resetting-the-password"></a>
72+
### Resetting The Password
73+
74+
#### The Password Reset Form
75+
76+
Next, we will define the routes necessary to actually reset the password once the user clicks on the password reset link that has been emailed to them and provides a new password. First, let's define the route that will display the reset password form that is displayed when the user clicks the reset password link. This route will receive a `token` parameter that we will use later to verify the password reset request:
77+
78+
Route::get('/reset-password/{token}', function ($token) {
79+
return view('auth.reset-password', ['token' => $token]);
80+
})->middleware(['guest'])->name('password.reset');
81+
82+
The view that is returned by this route should have a form containing an `email` field, a `password` field, a `password_confirmation` field, and a hidden `token` field, which should contain the value of the secret token received by our route.
83+
84+
#### Handling The Form Submission
85+
86+
Of course, we need to define a route to actually handle the password reset form submission. This route will be responsible for validating the incoming request and updating the user's password in the database:
87+
88+
use Illuminate\Auth\Events\PasswordReset;
89+
use Illuminate\Http\Request;
90+
use Illuminate\Support\Facades\Hash;
91+
use Illuminate\Support\Facades\Password;
92+
use Illuminate\Support\Str;
93+
94+
Route::post('/reset-password', function (Request $request) {
95+
$request->validate([
96+
'token' => 'required',
97+
'email' => 'required|email',
98+
'password' => 'required|min:8|confirmed',
99+
]);
100+
101+
$status = Password::reset(
102+
$request->only('email', 'password', 'password_confirmation', 'token'),
103+
function ($user, $password) use ($request) {
104+
$user->forceFill([
105+
'password' => Hash::make($password)
106+
])->save();
107+
108+
$user->setRememberToken(Str::random(60));
109+
110+
event(new PasswordReset($user));
111+
}
112+
);
113+
114+
return $status == Password::PASSWORD_RESET
115+
? redirect()->route('login')->with('status', trans($status))
116+
: back()->withErrors(['email' => trans($status)]);
117+
})->middleware(['guest'])->name('password.update');
118+
119+
Before moving on, let's examine this route in more detail. First, the request's `token`, 'email', and `password` attributes are validated. Next, we will use Laravel's built-in "password broker" to validate the password reset request credentials.
35120

36-
<a name="resetting-views"></a>
37-
## Views
121+
If the token, email address, and password given to the password broker are valid, the Closure passed to the `reset` method will be invoked. Within this Closure, which receives the user instance and the plain-text password, we may update the user's password in the database.
38122

39-
All of the views needed to perform password resets are automatically included in [Laravel Jetstream](https://jetstream.laravel.com). To learn how to install Jetstream, please consult the official [Jetstream documentation](https://jetstream.laravel.com).
123+
The `reset` method returns a "status" slug. This status may be translated using Laravel's [localization](/docs/{{version}}/localization) helpers in order to display a user-friendly message to the user regarding the status of their request. The translation of the password reset status is determined by your application's `resources/lang/{lang}/password.php` language file.
40124

41125
<a name="password-customization"></a>
42126
## Customization

‎verification.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
- [Introduction](#introduction)
44
- [Model Preparation](#model-preparation)
5-
- [Database Considerations](#verification-database)
5+
- [Database Preparation](#database-preparation)
66
- [Routing](#verification-routing)
77
- [The Email Verification Notice](#the-email-verification-notice)
88
- [The Email Verification Handler](#the-email-verification-handler)
@@ -39,8 +39,8 @@ To get started, verify that your `App\Models\User` model implements the `Illumin
3939

4040
Once this interface has been added to your model, newly registered users will automatically be sent an email containing an email verification link. As you can see by examining your `EventServiceProvider`, Laravel already contains a `SendEmailVerificationNotification` listener that is attached to the `Illuminate\Auth\Events\Registered` event.
4141

42-
<a name="verification-database"></a>
43-
### Database Considerations
42+
<a name="database-preparation"></a>
43+
### Database Preparation
4444

4545
Next, your `user` table must contain an `email_verified_at` column to store the date and time that the email address was verified. By default, the `users` table migration included with the Laravel framework already includes this column. So, all you need to do is run your database migrations:
4646

0 commit comments

Comments
 (0)