Middleware

Comment utiliser les middlewares Laravel pour filtrer et prétraiter les requêtes HTTP.

​

Qu’est-ce qu’un middleware

Un middleware est un mécanisme d’inspection et de filtrage des requêtes HTTP entrantes. Il permet d’insérer un traitement avant ou après le passage de la requête au contrôleur.

Par exemple, Laravel inclut un middleware d’authentification. Si l’utilisateur n’est pas authentifié, il redirige vers l’écran de connexion ; sinon, il laisse la requête poursuivre.

Au-delà de l’authentification, on peut écrire des middlewares pour la journalisation, la protection CSRF, la limitation de débit, etc. Pour les détails sur la protection CSRF de Laravel 13, consultez Protection CSRF.

Les middlewares utilisateurs sont généralement placés dans le répertoire app/Http/Middleware.

​

Middlewares intégrés

Laravel fournit par défaut deux groupes de middlewares : web et api. Le groupe web s’applique automatiquement à routes/web.php, et le groupe api à routes/api.php.

Groupe de middlewares web
EncryptCookies
AddQueuedCookiesToResponse
StartSession
ShareErrorsFromSession
PreventRequestForgery (protection CSRF)
SubstituteBindings

Des alias sont configurés pour les middlewares fréquemment utilisés.

Alias	Middleware
auth	Illuminate\Auth\Middleware\Authenticate
guest	Illuminate\Auth\Middleware\RedirectIfAuthenticated
verified	Illuminate\Auth\Middleware\EnsureEmailIsVerified
throttle	Illuminate\Routing\Middleware\ThrottleRequests

​

Créer un middleware

Utilisez la commande Artisan make:middleware pour créer un nouveau middleware.

php artisan make:middleware EnsureTokenIsValid

app/Http/Middleware/EnsureTokenIsValid.php est généré. Écrivez la logique de traitement dans la méthode handle.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureTokenIsValid
{
    /**
     * Traite la requête entrante.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->input('token') !== 'my-secret-token') {
            return redirect('/home');
        }

        return $next($request);
    }
}

L’appel de $next($request) transmet la requête au traitement suivant. Si la condition n’est pas satisfaite, retournez une redirection ou une réponse pour interrompre le flux.

​

Traitement avant / après la requête

Un middleware peut exécuter du code avant ou après la requête.

// Traitement avant la requête
public function handle(Request $request, Closure $next): Response
{
    // Placez ici le pré-traitement

    return $next($request);
}

// Traitement après la réponse
public function handle(Request $request, Closure $next): Response
{
    $response = $next($request);

    // Placez ici le post-traitement

    return $response;
}

​

Enregistrement d’un middleware

​

Middleware global

Pour l’exécuter sur toutes les requêtes, ajoutez-le à la pile globale via withMiddleware dans bootstrap/app.php.

// bootstrap/app.php
use App\Http\Middleware\EnsureTokenIsValid;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(EnsureTokenIsValid::class);
    });

append ajoute à la fin de la pile. Utilisez prepend pour l’ajouter au début.

​

Attribution à une route

Pour n’appliquer un middleware qu’à des routes spécifiques, appelez la méthode middleware dans la définition de route.

use App\Http\Middleware\EnsureTokenIsValid;

Route::get('/profile', function () {
    // ...
})->middleware(EnsureTokenIsValid::class);

Passez un tableau pour appliquer plusieurs middlewares.

Route::get('/', function () {
    // ...
})->middleware([First::class, Second::class]);

Pour exclure un middleware d’une route donnée, utilisez withoutMiddleware.

use App\Http\Middleware\EnsureTokenIsValid;

Route::middleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/', function () {
        // Le middleware s'applique
    });

    Route::get('/profile', function () {
        // Le middleware est exclu ici
    })->withoutMiddleware([EnsureTokenIsValid::class]);
});

​

Alias de middleware

Définissez un alias court pour un nom de classe long dans bootstrap/app.php.

// bootstrap/app.php
use App\Http\Middleware\EnsureUserIsSubscribed;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->alias([
            'subscribed' => EnsureUserIsSubscribed::class,
        ]);
    });

Appliquez ensuite l’alias aux routes.

Route::get('/profile', function () {
    // ...
})->middleware('subscribed');

​

Groupes de middlewares

Regroupez plusieurs middlewares sous une clé pour faciliter leur application aux routes. Utilisez appendToGroup ou prependToGroup dans bootstrap/app.php.

// bootstrap/app.php
use App\Http\Middleware\First;
use App\Http\Middleware\Second;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->appendToGroup('group-name', [
            First::class,
            Second::class,
        ]);
    });

Un groupe s’applique aux routes comme un middleware normal.

Route::get('/', function () {
    // ...
})->middleware('group-name');

Route::middleware(['group-name'])->group(function () {
    // ...
});

Pour ajouter des middlewares aux groupes web ou api existants, utilisez les méthodes dédiées.

// bootstrap/app.php
use App\Http\Middleware\EnsureUserIsSubscribed;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->web(append: [
            EnsureUserIsSubscribed::class,
        ]);
    });

​

Paramètres de middleware

Un middleware peut recevoir des paramètres additionnels. Ajoutez-les après $next dans handle.

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserHasRole
{
    public function handle(Request $request, Closure $next, string $role): Response
    {
        if (! $request->user()->hasRole($role)) {
            return redirect('/home');
        }

        return $next($request);
    }
}

Sur la définition de route, séparez le nom du middleware et les paramètres par :.

use App\Http\Middleware\EnsureUserHasRole;

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor');

Plusieurs paramètres sont séparés par une virgule.

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor,publisher');

​

Exemple : middleware de vérification d’authentification

Un exemple simple redirigeant les utilisateurs non connectés.

php artisan make:middleware RedirectIfNotAuthenticated

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class RedirectIfNotAuthenticated
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()) {
            return redirect('/login');
        }

        return $next($request);
    }
}

Appliquez-le à une route.

Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware(RedirectIfNotAuthenticated::class);

Laravel intègre le middleware auth pour l’authentification. Avant d’écrire le vôtre, vérifiez si un middleware existant satisfait vos besoins.

​

Prochaines étapes

Requêtes HTTP

Apprenez à recevoir les données de requête dans un contrôleur.