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

> Come usare i middleware di Laravel per filtrare e pre-elaborare le richieste HTTP.

## Cos'è un middleware

Un middleware è un meccanismo per ispezionare e filtrare le richieste HTTP in arrivo.
Puoi inserire logica prima e dopo che la richiesta arrivi al controller.

Ad esempio, Laravel include un middleware di autenticazione.
Se l'utente non è autenticato, effettua il redirect alla schermata di login; se lo è, lascia proseguire la richiesta all'interno dell'applicazione.

Oltre all'autenticazione puoi creare middleware per registrazione dei log, protezione CSRF, rate limiting e altri scopi. Per i dettagli sulla protezione CSRF di Laravel 13 consulta [Protezione CSRF](/it/csrf).

<Info>
  I middleware definiti dall'utente si trovano di norma nella directory `app/Http/Middleware`.
</Info>

```mermaid theme={null}
flowchart TD
    A["Richiesta HTTP"] --> B["Middleware globali<br>(si applicano a tutte le richieste)"]
    B --> C["Middleware di route<br>(si applicano a route specifiche)"]
    C --> D["Controller / Closure"]
    D --> E["Generazione della risposta"]
    E --> F["Middleware di route<br>(post-elaborazione)"]
    F --> G["Middleware globali<br>(post-elaborazione)"]
    G --> H["Risposta HTTP"]
```

## Middleware integrati

Laravel prevede di default due gruppi di middleware: `web` e `api`.
A `routes/web.php` viene applicato automaticamente il gruppo `web` e a `routes/api.php` il gruppo `api`.

| Gruppo di middleware `web`                |
| ----------------------------------------- |
| `EncryptCookies`                          |
| `AddQueuedCookiesToResponse`              |
| `StartSession`                            |
| `ShareErrorsFromSession`                  |
| `PreventRequestForgery` (protezione CSRF) |
| `SubstituteBindings`                      |

I middleware più comuni hanno inoltre degli alias per essere richiamati con nomi brevi.

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

## Creazione di un middleware

Crea un nuovo middleware con il comando Artisan `make:middleware`.

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

Viene generato `app/Http/Middleware/EnsureTokenIsValid.php`.
Scrivi la logica di elaborazione della richiesta nel metodo `handle`.

```php theme={null}
<?php

namespace App\Http\Middleware;

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

class EnsureTokenIsValid
{
    /**
     * Gestisce la richiesta in arrivo
     *
     * @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);
    }
}
```

Chiamando `$next($request)` la richiesta prosegue nell'elaborazione successiva.
Se la condizione non è soddisfatta, restituisci un redirect o una risposta per interrompere.

### Elaborazione prima e dopo la richiesta

Il middleware può eseguire logica **prima** o **dopo** la richiesta.

```php theme={null}
// Elaborazione prima della richiesta
public function handle(Request $request, Closure $next): Response
{
    // Pre-elaborazione qui

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

```php theme={null}
// Elaborazione dopo la risposta
public function handle(Request $request, Closure $next): Response
{
    $response = $next($request);

    // Post-elaborazione qui

    return $response;
}
```

## Registrazione dei middleware

### Middleware globali

Se vuoi eseguire un middleware per ogni richiesta, aggiungilo allo stack globale in `withMiddleware` di `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` aggiunge in coda allo stack. Per aggiungere in testa usa `prepend`.

### Applicazione a route

Per applicare il middleware solo a certe route, chiama il metodo `middleware` nella definizione della route.

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

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

Per più middleware passa un array.

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

Per escludere un middleware da una route specifica usa `withoutMiddleware`.

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

Route::middleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/', function () {
        // A questa route si applica il middleware
    });

    Route::get('/profile', function () {
        // Questa route esclude il middleware
    })->withoutMiddleware([EnsureTokenIsValid::class]);
});
```

### Alias dei middleware

Puoi definire alias brevi per nomi di classi lunghi. Configura in `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,
        ]);
    });
```

Poi puoi applicarli alle route tramite l'alias.

```php theme={null}
Route::get('/profile', function () {
    // ...
})->middleware('subscribed');
```

## Gruppi di middleware

Raggruppando più middleware in un'unica chiave, applicarli alle route diventa più semplice.
In `bootstrap/app.php` usa `appendToGroup` o `prependToGroup`.

```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 gruppo si applica come un middleware normale.

```php theme={null}
Route::get('/', function () {
    // ...
})->middleware('group-name');

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

Per aggiungere middleware ai gruppi esistenti `web` o `api` ci sono metodi dedicati.

```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,
        ]);
    });
```

## Parametri dei middleware

Il middleware può ricevere parametri aggiuntivi.
Aggiungi il parametro dopo l'argomento `$next` del metodo `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);
    }
}
```

Nella definizione della route separa nome del middleware e parametro con `:`.

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

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

Separa più parametri con la virgola.

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

## Esempio pratico: middleware di controllo dell'autenticazione

Esempio semplice che reindirizza gli utenti non autenticati.

```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);
    }
}
```

Applicalo alla route.

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

<Tip>
  Laravel include il middleware `auth` per l'autenticazione. Prima di implementarne uno personalizzato, verifica se puoi soddisfare i tuoi requisiti con i middleware esistenti.
</Tip>

## Prossimi passi

<Card title="Richieste HTTP" icon="globe" href="/it/requests">
  Impara come ricevere i dati delle richieste nei controller.
</Card>


## Related topics

- [Laravel Folio](/it/folio.md)
- [Autenticazione OAuth 2.0 - Google Sheets API for Laravel](/it/packages/laravel-google-sheets/oauth.md)
- [Laravel Pennant](/it/pennant.md)
- [Laravel AI SDK](/it/ai-sdk.md)
- [Laravel Sentinel — indagine sul middleware di protezione delle rotte](/it/blog/sentinel-introduction.md)