Restablecer contraseñas

• Introducción
  • Preparación del modelo
  • Preparación de la base de datos
  • Configuración de hosts confiables
• Rutas
  • Solicitar el enlace para restablecer la contraseña
  • Restablecer la contraseña
• Eliminar tokens expirados
• Personalización

#Introducción

La mayoría de las aplicaciones web ofrecen una forma para que los usuarios restablezcan sus contraseñas olvidadas. En lugar de obligarle a implementar esto manualmente para cada aplicación que cree, Laravel proporciona servicios convenientes para enviar enlaces de restablecimiento de contraseña y restablecer contraseñas de forma segura.

#Preparación del modelo

Antes de usar las funciones de restablecimiento de contraseña de Laravel, el modelo App\Models\User de su aplicación debe usar el trait Illuminate\Notifications\Notifiable. Normalmente, este trait ya está incluido en el modelo App\Models\User predeterminado que se crea con nuevas aplicaciones Laravel.

Luego, verifique que su modelo App\Models\User implemente el contrato Illuminate\Contracts\Auth\CanResetPassword. El modelo App\Models\User incluido con el framework ya implementa esta interfaz y usa el trait Illuminate\Auth\Passwords\CanResetPassword para incluir los métodos necesarios para implementar la interfaz.

#Preparación de la base de datos

Debe crearse una tabla para almacenar los tokens de restablecimiento de contraseña de su aplicación. La migración para esta tabla está incluida en la aplicación Laravel predeterminada, por lo que solo necesita migrar su base de datos para crear esta tabla:

php artisan migrate

#Configuración de hosts confiables

Por defecto, Laravel responderá a todas las solicitudes que reciba sin importar el contenido del encabezado HTTP Host. Además, el valor del encabezado Host se usará al generar URLs absolutas a su aplicación durante una solicitud web.

Normalmente, debería configurar su servidor web, como Nginx o Apache, para que solo envíe solicitudes a su aplicación que coincidan con un nombre de host dado. Sin embargo, si no puede personalizar directamente su servidor web y necesita indicar a Laravel que solo responda a ciertos nombres de host, puede hacerlo habilitando el middleware App\Http\Middleware\TrustHosts para su aplicación. Esto es especialmente importante cuando su aplicación ofrece funcionalidad de restablecimiento de contraseña.

Para aprender más sobre este middleware, consulte la documentación del middleware TrustHosts.

#Rutas

Para implementar correctamente el soporte que permite a los usuarios restablecer sus contraseñas, necesitaremos definir varias rutas. Primero, necesitaremos un par de rutas para permitir que el usuario solicite un enlace de restablecimiento de contraseña a través de su dirección de correo electrónico. Segundo, necesitaremos un par de rutas para manejar el restablecimiento real de la contraseña una vez que el usuario visite el enlace de restablecimiento enviado por correo y complete el formulario de restablecimiento.

#Solicitar el enlace para restablecer la contraseña

#El formulario para solicitar el enlace de restablecimiento de contraseña

Primero, definiremos las rutas necesarias para solicitar enlaces de restablecimiento de contraseña. Para comenzar, definiremos una ruta que devuelve una vista con el formulario para solicitar el enlace de restablecimiento:

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

La vista que devuelve esta ruta debe tener un formulario que contenga un campo email, que permitirá al usuario solicitar un enlace de restablecimiento de contraseña para una dirección de correo electrónico dada.

#Manejo del envío del formulario

Luego, definiremos una ruta que maneje la solicitud de envío del formulario desde la vista "olvidé mi contraseña". Esta ruta será responsable de validar la dirección de correo electrónico y enviar la solicitud de restablecimiento de contraseña al usuario correspondiente:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Password;

Route::post('/forgot-password', function (Request $request) {
    $request->validate(['email' => 'required|email']);

    $status = Password::sendResetLink(
        $request->only('email')
    );

    return $status === Password::RESET_LINK_SENT
                ? back()->with(['status' => __($status)])
                : back()->withErrors(['email' => __($status)]);
})->middleware('guest')->name('password.email');

Antes de continuar, examinemos esta ruta con más detalle. Primero, se valida el atributo email de la solicitud. Luego, usaremos el "password broker" incorporado de Laravel (a través de la fachada Password) para enviar un enlace de restablecimiento de contraseña al usuario. El password broker se encargará de recuperar al usuario por el campo dado (en este caso, la dirección de correo electrónico) y enviar al usuario un enlace de restablecimiento mediante el sistema de notificaciones integrado de Laravel.

El método sendResetLink devuelve un "slug" de estado. Este estado puede traducirse usando las ayudas de localización de Laravel para mostrar un mensaje amigable al usuario sobre el estado de su solicitud. La traducción del estado del restablecimiento de contraseña se determina por el archivo de idioma lang/{lang}/passwords.php de su aplicación. Una entrada para cada posible valor del slug de estado se encuentra dentro del archivo de idioma passwords.

Quizás se pregunte cómo Laravel sabe cómo recuperar el registro del usuario desde la base de datos de su aplicación al llamar al método sendResetLink de la fachada Password. El password broker de Laravel utiliza los "user providers" de su sistema de autenticación para recuperar los registros de la base de datos. El proveedor de usuarios usado por el password broker se configura dentro del arreglo passwords en el archivo de configuración config/auth.php. Para aprender más sobre cómo escribir proveedores de usuarios personalizados, consulte la documentación de autenticación.

#Restablecer la contraseña

#El formulario de restablecimiento de contraseña

Luego, definiremos las rutas necesarias para restablecer la contraseña una vez que el usuario haga clic en el enlace de restablecimiento enviado por correo y proporcione una nueva contraseña. Primero, definamos la ruta que mostrará el formulario de restablecimiento de contraseña que se muestra cuando el usuario hace clic en el enlace. Esta ruta recibirá un parámetro token que usaremos más adelante para verificar la solicitud de restablecimiento:

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

La vista que devuelve esta ruta debe mostrar un formulario que contenga un campo email, un campo password, un campo password_confirmation y un campo oculto token, que debe contener el valor del secreto $token recibido por nuestra ruta.

#Manejo del envío del formulario

Por supuesto, necesitamos definir una ruta para manejar el envío del formulario de restablecimiento de contraseña. Esta ruta será responsable de validar la solicitud entrante y actualizar la contraseña del usuario en la base de datos:

use App\Models\User;
use Illuminate\Auth\Events\PasswordReset;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Password;
use Illuminate\Support\Str;

Route::post('/reset-password', function (Request $request) {
    $request->validate([
        'token' => 'required',
        'email' => 'required|email',
        'password' => 'required|min:8|confirmed',
    ]);

    $status = Password::reset(
        $request->only('email', 'password', 'password_confirmation', 'token'),
        function (User $user, string $password) {
            $user->forceFill([
                'password' => Hash::make($password)
            ])->setRememberToken(Str::random(60));

            $user->save();

            event(new PasswordReset($user));
        }
    );

    return $status === Password::PASSWORD_RESET
                ? redirect()->route('login')->with('status', __($status))
                : back()->withErrors(['email' => [__($status)]]);
})->middleware('guest')->name('password.update');

Antes de continuar, examinemos esta ruta con más detalle. Primero, se validan los atributos token, email y password de la solicitud. Luego, usaremos el "password broker" incorporado de Laravel (a través de la fachada Password) para validar las credenciales de la solicitud de restablecimiento de contraseña.

Si el token, la dirección de correo electrónico y la contraseña proporcionados al password broker son válidos, se invocará la función anónima pasada al método reset. Dentro de esta función, que recibe la instancia del usuario y la contraseña en texto plano proporcionada en el formulario de restablecimiento, podemos actualizar la contraseña del usuario en la base de datos.

El método reset devuelve un "slug" de estado. Este estado puede traducirse usando las ayudas de localización de Laravel para mostrar un mensaje amigable al usuario sobre el estado de su solicitud. La traducción del estado del restablecimiento de contraseña se determina por el archivo de idioma lang/{lang}/passwords.php de su aplicación. Una entrada para cada posible valor del slug de estado se encuentra dentro del archivo de idioma passwords. Si su aplicación no contiene un directorio lang, puede crearlo usando el comando Artisan lang:publish.

Antes de continuar, quizás se pregunte cómo Laravel sabe cómo recuperar el registro del usuario desde la base de datos de su aplicación al llamar al método reset de la fachada Password. El password broker de Laravel utiliza los "user providers" de su sistema de autenticación para recuperar los registros de la base de datos. El proveedor de usuarios usado por el password broker se configura dentro del arreglo passwords en el archivo de configuración config/auth.php. Para aprender más sobre cómo escribir proveedores de usuarios personalizados, consulte la documentación de autenticación.

#Eliminar tokens expirados

Los tokens de restablecimiento de contraseña que han expirado seguirán presentes en su base de datos. Sin embargo, puede eliminar fácilmente estos registros usando el comando Artisan auth:clear-resets:

php artisan auth:clear-resets

Si desea automatizar este proceso, considere agregar el comando al scheduler de su aplicación:

$schedule->command('auth:clear-resets')->everyFifteenMinutes();

#Personalización

#Personalización del enlace de restablecimiento

Puede personalizar la URL del enlace de restablecimiento de contraseña usando el método createUrlUsing proporcionado por la clase de notificación ResetPassword. Este método acepta una función anónima que recibe la instancia del usuario que recibe la notificación y el token del enlace de restablecimiento. Normalmente, debería llamar a este método desde el método boot del proveedor de servicios App\Providers\AuthServiceProvider:

use App\Models\User;
use Illuminate\Auth\Notifications\ResetPassword;

/**
 * Registrar cualquier servicio de autenticación/autorización.
 */
public function boot(): void
{
    ResetPassword::createUrlUsing(function (User $user, string $token) {
        return 'https://example.com/reset-password?token='.$token;
    });
}

#Personalización del correo de restablecimiento

Puede modificar fácilmente la clase de notificación usada para enviar el enlace de restablecimiento de contraseña al usuario. Para comenzar, sobrescriba el método sendPasswordResetNotification en su modelo App\Models\User. Dentro de este método, puede enviar la notificación usando cualquier clase de notificación creada por usted. El $token de restablecimiento de contraseña es el primer argumento recibido por el método. Puede usar este $token para construir la URL de restablecimiento de contraseña que desee y enviar su notificación al usuario:

use App\Notifications\ResetPasswordNotification;

/**
 * Enviar una notificación de restablecimiento de contraseña al usuario.
 *
 * @param  string  $token
 */
public function sendPasswordResetNotification($token): void
{
    $url = 'https://example.com/reset-password?token='.$token;

    $this->notify(new ResetPasswordNotification($url));
}