Reset delle Password

• Introduzione
• Routing
• Cancellazione dei Token Scaduti
• Personalizzazione

Introduzione

La maggior parte delle applicazioni web consente agli utenti di reimpostare le password dimenticate. Invece di dover implementare questa funzionalità manualmente per ogni applicazione che crei, Laravel offre servizi comodi per inviare link di reimpostazione della password e per reimpostare le password in modo sicuro.

Vuoi iniziare rapidamente? Installa un application starter kit di Laravel in una nuova applicazione Laravel. Gli starter kit di Laravel si occuperanno di creare tutto il sistema di autenticazione, inclusa la reimpostazione delle password dimenticate.

Preparazione del modello

Prima di utilizzare le funzionalità di reset della password di Laravel, il modello App\Models\User della tua applicazione deve utilizzare il trait Illuminate\Notifications\Notifiable. Di solito, questo trait è già incluso nel modello predefinito App\Models\User creato con le nuove applicazioni Laravel.

Successivamente, verifica che il modello App\Models\User implementi il contratto Illuminate\Contracts\Auth\CanResetPassword. Il modello App\Models\User incluso nel framework già implementa questa interfaccia e utilizza il trait Illuminate\Auth\Passwords\CanResetPassword per includere i metodi necessari all’implementazione dell’interfaccia.

Preparazione del Database

Deve essere creata una tabella per memorizzare i token per il reset della password della tua applicazione. Tipicamente, questo è incluso nella migrazione del database predefinita di Laravel 0001_01_01_000000_create_users_table.php.

Configurazione degli Host fidati

Per default, Laravel risponde a tutte le richieste che riceve indipendentemente dal contenuto dell’header Host della richiesta HTTP. Inoltre, il valore dell’header Host viene utilizzato quando si generano URL assoluti alla tua applicazione durante una richiesta web.

Di solito, dovresti configurare il tuo server web, come Nginx o Apache, per inviare alla tua applicazione solo le richieste che corrispondono a un determinato hostname. Tuttavia, se non hai la possibilità di personalizzare direttamente il tuo server web e hai bisogno di istruirlo affinché Laravel risponda solo a determinati hostname, puoi farlo utilizzando il metodo middleware trustHosts nel file bootstrap/app.php della tua applicazione. Questo è particolarmente importante quando la tua applicazione offre funzionalità di reset della password.

Per saperne di più su questo metodo middleware, consulta la documentazione del middleware TrustHosts.

Routing

Per implementare correttamente il supporto che permette agli utenti di reimpostare le proprie password, dobbiamo definire diverse route. Prima di tutto, avremo bisogno di un paio di route per consentire all’utente di richiedere un link di reimpostazione della password tramite il proprio indirizzo email. In secondo luogo, avremo bisogno di un paio di route per gestire effettivamente la reimpostazione della password una volta che l’utente visita il link di reimpostazione inviato via email e completa il modulo di reimpostazione della password.

Richiedere il link per reimpostare la password

Il Modulo per Richiedere il Link di Reimpostazione della Password

Per prima cosa, definiamo le route necessarie per richiedere i link di reimpostazione della password. Iniziamo definendo una route che restituisce una view con il modulo per richiedere il link di reimpostazione della password:

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

La view restituita da questa route dovrebbe avere un modulo con un campo email, che permetterà all’utente di richiedere un link di reimpostazione della password per un determinato indirizzo email.

Gestione dell’Invio del Modulo

Successivamente, definiremo una rotta che gestisce la richiesta di invio del modulo dalla vista "password dimenticata". Questa rotta sarà responsabile della validazione dell’indirizzo email e dell’invio della richiesta di reset della password all’utente corrispondente:

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');

Prima di procedere, esaminiamo questa rotta più in dettaglio. Innanzitutto, viene validato l’attributo email della richiesta. Successivamente, utilizzeremo il "password broker" integrato di Laravel (tramite la facade Password) per inviare un link di reset della password all’utente. Il password broker si occuperà di recuperare l’utente basandosi sul campo fornito (in questo caso, l’indirizzo email) e inviare all’utente un link per resettare la password attraverso il sistema di notifiche integrato di Laravel.

Il metodo sendResetLink restituisce uno slug di "stato". Questo stato può essere tradotto utilizzando gli helper di localizzazione di Laravel per mostrare un messaggio chiaro all’utente riguardo lo stato della loro richiesta. La traduzione dello stato del reset della password è determinata dal file di lingua lang/{lang}/passwords.php della tua applicazione. Un’entrata per ogni valore possibile dello slug di stato si trova all’interno del file di lingua passwords.

Di default, lo scheletro dell’applicazione Laravel non include la directory lang. Se desideri personalizzare i file di lingua di Laravel, puoi pubblicarli tramite il comando Artisan lang:publish.

Potresti chiederti come Laravel sappia come recuperare il record utente dal database della tua applicazione quando chiami il metodo sendResetLink della facade Password. Il password broker di Laravel utilizza i "provider di utenti" del tuo sistema di autenticazione per recuperare i record dal database. Il provider di utenti usato dal password broker è configurato all’interno dell’array di configurazione passwords del tuo file di configurazione config/auth.php. Per saperne di più sulla scrittura di provider di utenti personalizzati, consulta la documentazione sull’autenticazione.

Quando implementi manualmente il reset della password, è necessario definire tu stesso il contenuto delle viste e delle rotte. Se desideri un’implementazione che includa tutta la logica necessaria per l’autenticazione e la verifica, dai un’occhiata ai kit di avvio delle applicazioni Laravel.

Reimpostare la Password

Il Modulo di Reimpostazione della Password

Successivamente, definiremo le rotte necessarie per reimpostare effettivamente la password una volta che l’utente clicca sul link di reimpostazione password inviato via email e fornisce una nuova password. Prima, definiamo la rotta che mostrerà il modulo di reimpostazione della password che viene visualizzato quando l’utente clicca sul link di reimpostazione password. Questa rotta riceverà un parametro token che useremo successivamente per verificare la richiesta di reimpostazione della password:

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

La vista restituita da questa rotta dovrebbe mostrare un modulo contenente un campo email, un campo password, un campo password_confirmation e un campo nascosto token, che dovrebbe contenere il valore del segreto $token ricevuto dalla nostra rotta.

Gestione dell’invio del modulo

Naturalmente, dobbiamo definire una rotta per gestire effettivamente l’invio del modulo di reimpostazione della password. Questa rotta sarà responsabile della validazione della richiesta in arrivo e dell’aggiornamento della password dell’utente nel database:

    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');

Prima di procedere, esaminiamo questa rotta più dettagliatamente. Innanzitutto, vengono validate le proprietà token, email e password della richiesta. Successivamente, utilizzeremo il "password broker" integrato di Laravel (tramite la facade Password) per convalidare le credenziali della richiesta di reimpostazione della password.

Se il token, l’indirizzo email e la password forniti al password broker sono validi, verrà invocata la funzione di callback passata al metodo reset. All’interno di questa callback, che riceve l’istanza dell’utente e la password in chiaro fornita al modulo di reimpostazione della password, possiamo aggiornare la password dell’utente nel database.

Il metodo reset restituisce uno slug di "status". Questo status può essere tradotto utilizzando gli helper di localizzazione di Laravel per mostrare un messaggio comprensibile all’utente riguardo lo stato della sua richiesta. La traduzione dello status di reimpostazione della password è determinata dal file di lingua lang/{lang}/passwords.php della tua applicazione. È presente una voce per ogni valore possibile dello slug dello status all’interno del file di lingua passwords. Se la tua applicazione non contiene una directory lang, puoi crearla usando il comando Artisan lang:publish.

Prima di procedere, potresti chiederti come Laravel sappia come recuperare il record dell’utente dal database della tua applicazione quando chiama il metodo reset della facade Password. Il password broker di Laravel utilizza i "provider di utenti" del tuo sistema di autenticazione per recuperare i record dal database. Il provider di utenti utilizzato dal password broker è configurato all’interno dell’array di configurazione passwords del tuo file di configurazione config/auth.php. Per saperne di più sulla scrittura di provider di utenti personalizzati, consulta la documentazione sull’autenticazione.

Cancellazione dei Token Scaduti

I token per il reset della password scaduti rimarranno nel tuo database. Tuttavia, puoi facilmente eliminare questi record usando il comando Artisan auth:clear-resets:

php artisan auth:clear-resets

Se desideri automatizzare questo processo, considera di aggiungere il comando allo scheduler della tua applicazione:

use Illuminate\Support\Facades\Schedule;

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

Personalizzazione

Personalizzazione del Link per il Reset

Puoi personalizzare l’URL del link per reimpostare la password utilizzando il metodo createUrlUsing fornito dalla classe di notifica ResetPassword. Questo metodo accetta una closure che riceve l’istanza dell’utente che riceve la notifica e il token del link per il reset della password. Di solito, dovresti chiamare questo metodo dal metodo boot del service provider App\Providers\AppServiceProvider:

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

/**
 * Inizializza i servizi dell'applicazione.
 */
public function boot(): void
{
    ResetPassword::createUrlUsing(function (User $user, string $token) {
        return 'https://example.com/reset-password?token='.$token;
    });
}

Personalizzazione Email di Reset

Puoi facilmente modificare la classe di notifica usata per inviare il link di reset della password all’utente. Per iniziare, sovrascrivi il metodo sendPasswordResetNotification nel tuo modello App\Models\User. All’interno di questo metodo, puoi inviare la notifica usando qualsiasi notification class che hai creato. Il $token per il reset della password è il primo argomento del metodo. Puoi usare questo $token per costruire l’URL di reset della password che preferisci e inviare la notifica all’utente:

use App\Notifications\ResetPasswordNotification;

/**
 * Send a password reset notification to the user.
 *
 * @param  string  $token
 */
public function sendPasswordResetNotification($token): void
{
    $url = 'https://example.com/reset-password?token='.$token;

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