> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/fr/csrf).

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

```mermaid theme={null}
flowchart TD
    A["Requête HTTP"] --> B["Middlewares globaux<br>(appliqués à toutes les requêtes)"]
    B --> C["Middlewares de route<br>(appliqués à des routes spécifiques)"]
    C --> D["Contrôleur / Closure"]
    D --> E["Génération de la réponse"]
    E --> F["Middlewares de route<br>(post-traitement)"]
    F --> G["Middlewares globaux<br>(post-traitement)"]
    G --> H["Réponse HTTP"]
```

## 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.

```shell theme={null}
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 theme={null}
<?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.

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

    return $next($request);
}
```

```php theme={null}
// 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`.

```php theme={null}
// 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.

```php theme={null}
use App\Http\Middleware\EnsureTokenIsValid;

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

Passez un tableau pour appliquer plusieurs middlewares.

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

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

```php theme={null}
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`.

```php theme={null}
// 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.

```php theme={null}
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`.

```php theme={null}
// 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.

```php theme={null}
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.

```php theme={null}
// 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 theme={null}
<?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 `:`.

```php theme={null}
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.

```php theme={null}
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.

```shell theme={null}
php artisan make:middleware RedirectIfNotAuthenticated
```

```php theme={null}
<?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.

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

<Tip>
  Laravel intègre le middleware `auth` pour l'authentification. Avant d'écrire le vôtre, vérifiez si un middleware existant satisfait vos besoins.
</Tip>

## Prochaines étapes

<Card title="Requêtes HTTP" icon="globe" href="/fr/requests">
  Apprenez à recevoir les données de requête dans un contrôleur.
</Card>


## Related topics

- [Laravel Folio](/fr/folio.md)
- [Laravel AI SDK](/fr/ai-sdk.md)
- [Authentification OAuth 2.0 - Google Sheets API for Laravel](/fr/packages/laravel-google-sheets/oauth.md)
- [Laravel Pennant](/fr/pennant.md)
- [Laravel Sentinel — analyse du middleware de protection des routes](/fr/blog/sentinel-introduction.md)