From c7870279a9ef5a34fb0db54665aa910b0b975dd4 Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Tue, 24 Jun 2025 15:55:50 -0500 Subject: [PATCH 1/3] document the password reset `cache` driver document https://github.com/laravel/framework/pull/53428 I modeled the wording and organization after the `session.md` docs for hopefully a little consistency. --- passwords.md | 51 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/passwords.md b/passwords.md index d9102bfe7eb..062c999aac4 100644 --- a/passwords.md +++ b/passwords.md @@ -1,8 +1,9 @@ # Resetting Passwords - [Introduction](#introduction) + - [Configuration](#configuration) + - [Driver Prerequisites](#driver-prerequisites) - [Model Preparation](#model-preparation) - - [Database Preparation](#database-preparation) - [Configuring Trusted Hosts](#configuring-trusted-hosts) - [Routing](#routing) - [Requesting the Password Reset Link](#requesting-the-password-reset-link) @@ -18,6 +19,47 @@ Most web applications provide a way for users to reset their forgotten passwords > [!NOTE] > Want to get started fast? Install a Laravel [application starter kit](/docs/{{version}}/starter-kits) in a fresh Laravel application. Laravel's starter kits will take care of scaffolding your entire authentication system, including resetting forgotten passwords. + +### Configuration + +Your application's password reset configuration file is stored at `config/auth.php`. Be sure to review the options available to you in this file. By default, Laravel is configured to use the `database` password reset driver. + +The password reset `driver` configuration option defines where password reset data will be stored. Laravel includes two drivers: + +
+ +- `database` - password resets are stored in a relational database. +- `cache` - password resets are stored in one of your cache based stores. + +
+ + +### Driver Prerequisites + + +#### Database + +When using the default `database` driver, 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. + + +#### Cache + +There is also a cache driver available for handling password resets, which does not require a dedicated database table. + +```php +'passwords' => [ + 'users' => [ + 'driver' => 'cache', + 'provider' => 'users', + 'store' => 'passwords', //optional + 'expire' => 60, + 'throttle' => 60, + ], +], +``` + +To prevent a call to `artisan cache:clear` from flushing your password resets, you can optionally specify a separate cache store with the `store` configuration key. The value should point to a store configured in `config/cache.php`. + ### Model Preparation @@ -25,11 +67,6 @@ Before using the password reset features of Laravel, your application's `App\Mod 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. - -### Database Preparation - -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. - ### Configuring Trusted Hosts @@ -160,7 +197,7 @@ Before moving on, you may be wondering how Laravel knows how to retrieve the use ## Deleting Expired Tokens -Password reset tokens that have expired will still be present within your database. However, you may easily delete these records using the `auth:clear-resets` Artisan command: +If you are using the `database` driver, password reset tokens that have expired will still be present within your database. However, you may easily delete these records using the `auth:clear-resets` Artisan command: ```shell php artisan auth:clear-resets From 12ff39a0e131673970fc9840eabdc69c3f889cd6 Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Tue, 24 Jun 2025 17:04:04 -0500 Subject: [PATCH 2/3] add note about how we key the entries --- passwords.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/passwords.md b/passwords.md index 062c999aac4..3de83c8b207 100644 --- a/passwords.md +++ b/passwords.md @@ -44,7 +44,7 @@ When using the default `database` driver, a table must be created to store your #### Cache -There is also a cache driver available for handling password resets, which does not require a dedicated database table. +There is also a cache driver available for handling password resets, which does not require a dedicated database table. Entries are keyed by the user's email, so ensure you are not using that key within the cache store elsewhere. ```php 'passwords' => [ From 6fdf9101412b4a4ac537b1b3a2b0abd8726144e6 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Tue, 1 Jul 2025 18:45:29 +0200 Subject: [PATCH 3/3] formatting --- passwords.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/passwords.md b/passwords.md index 3de83c8b207..75ae7432e47 100644 --- a/passwords.md +++ b/passwords.md @@ -28,8 +28,8 @@ The password reset `driver` configuration option defines where password reset da
-- `database` - password resets are stored in a relational database. -- `cache` - password resets are stored in one of your cache based stores. +- `database` - password reset data is stored in a relational database. +- `cache` - password reset data is stored in one of your cache based stores.
@@ -44,21 +44,21 @@ When using the default `database` driver, a table must be created to store your #### Cache -There is also a cache driver available for handling password resets, which does not require a dedicated database table. Entries are keyed by the user's email, so ensure you are not using that key within the cache store elsewhere. +There is also a cache driver available for handling password resets, which does not require a dedicated database table. Entries are keyed by the user's email address, so ensure you are not using email addresses as a cache key elsewhere in your application: ```php 'passwords' => [ 'users' => [ 'driver' => 'cache', 'provider' => 'users', - 'store' => 'passwords', //optional + 'store' => 'passwords', // Optional... 'expire' => 60, 'throttle' => 60, ], ], ``` -To prevent a call to `artisan cache:clear` from flushing your password resets, you can optionally specify a separate cache store with the `store` configuration key. The value should point to a store configured in `config/cache.php`. +To prevent a call to `artisan cache:clear` from flushing your password reset data, you can optionally specify a separate cache store with the `store` configuration key. The value should correspond to a store configured in your `config/cache.php` configuration value. ### Model Preparation