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

# Registrazione e ambito di applicazione dei middleware di un pacchetto

> Analisi dell'implementazione del Router di Laravel 13: registrazione degli alias dei middleware di un pacchetto, applicazione esplicita, come evitare di sovrascrivere i gruppi e verifica con la cache.

Quando aggiungi funzionalità HTTP a un pacchetto, tieni separati due aspetti: rendere disponibile un middleware e applicarlo alle richieste dell'applicazione che lo utilizza. Se progetti il pacchetto in modo che la sola installazione non modifichi il comportamento di tutte le route, è più facile gestire l'impatto dell'adozione e la compatibilità futura.

Questa pagina presuppone la conoscenza delle [basi dello sviluppo di pacchetti](/it/advanced/package-development) e fa riferimento alla documentazione ufficiale di Laravel `13.x` e all'implementazione del Framework `v13.36.0`. Per scrivere i middleware ordinari, consulta [Middleware](/it/middleware).

## Separare registrazione, applicazione ed esecuzione

`Router::aliasMiddleware()` registra nell'array del Router l'alias come chiave e il nome della classe come valore. Non crea istanze del middleware né lo applica alle route.

```mermaid theme={null}
flowchart TD
    A["boot del provider"] --> B["Registrazione di nome e classe<br>con aliasMiddleware"]
    C["Definizione della route"] --> D["Indicazione dei nomi da applicare<br>con middleware"]
    B --> E["Determinazione della route della richiesta"]
    D --> E
    E --> F["Espansione di alias e gruppi<br>applicazione di esclusioni e priorità"]
    F --> G["La Pipeline esegue i middleware"]
```

| Operazione | Ruolo | Cosa non fa da sola |
| - | - | - |
| `aliasMiddleware()` | Registra la corrispondenza tra nome e classe | Applicazione alle richieste |
| `middleware()` della route | Assegna il middleware alla route interessata | Implementazione della classe middleware |
| `middlewareGroup()` | Imposta il contenuto di un gruppo con nome | Aggiunta ai middleware globali |
| Aggiunta allo stack globale dell'HTTP Kernel | Coinvolge tutte le richieste | Supporto all'esclusione per singola route |

Il nome dell'alias è un'API pubblica. Evita i nomi predefiniti come `auth` o `throttle` e i nomi generici che possono entrare in conflitto con altri pacchetti, e aggiungi un prefisso specifico del pacchetto. Se registri di nuovo la stessa chiave, `aliasMiddleware()` sovrascrive la corrispondenza precedente.

## Esporre l'alias dal provider

Nell'esempio seguente creiamo un middleware che aggiunge alla risposta un header identificativo fisso. Non si tratta di un esempio di autenticazione, autorizzazione o controllo degli accessi. Si presuppone che il PSR-4 di Composer associ `Acme\Courier\` a `src/` e che il provider sia registrato tramite [rilevamento automatico](/it/advanced/package-discovery) o manualmente.

```php src/Http/Middleware/AddCourierHeader.php theme={null}
<?php

namespace Acme\Courier\Http\Middleware;

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

class AddCourierHeader
{
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);

        $response->headers->set('X-Acme-Courier', 'enabled');

        return $response;
    }
}
```

Usa il Router in `boot()`. Gli argomenti di `boot()` vengono iniettati dal service container, quindi per registrare il middleware non è necessario modificare automaticamente il `bootstrap/app.php` dell'utente.

```php src/CourierServiceProvider.php theme={null}
<?php

namespace Acme\Courier;

use Acme\Courier\Http\Middleware\AddCourierHeader;
use Illuminate\Routing\Router;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(Router $router): void
    {
        $router->aliasMiddleware('acme-courier.header', AddCourierHeader::class);
    }
}
```

Avvia questo provider come un normale provider. Se sposti la registrazione dell'alias in un provider differito, eseguito solo quando viene risolto un altro servizio, non c'è più la garanzia che l'alias sia registrato nel momento in cui la route ne ha bisogno.

### L'utente lo applica per singola route

Nel file `routes/web.php` dell'applicazione che utilizza il pacchetto, assegna il middleware solo alle route che ne hanno bisogno.

```php routes/web.php theme={null}
<?php

use Illuminate\Support\Facades\Route;

Route::get('/courier-status', function () {
    return response()->json(['available' => true]);
})->middleware('acme-courier.header');
```

Puoi anche non fornire un alias e indicare direttamente il nome della classe, come in `->middleware(AddCourierHeader::class)`. Scegli in base alla necessità di offrire agli utenti un nome breve.

Anche quando è il pacchetto stesso a fornire le route, indica esplicitamente nel file delle route i middleware necessari. `loadRoutesFrom()` non aggiunge automaticamente `web` o `api`. Per il metodo di registrazione e la gestione della cache delle route, consulta [Registrazione e cache delle route dei pacchetti](/it/advanced/package-routes).

## L'applicazione all'intera applicazione è una scelta dell'utente

Per applicare il middleware a tutte le route `web` dell'applicazione, l'utente aggiunge la configurazione seguente alla callback `withMiddleware()` esistente. Non si tratta di un esempio che sostituisce la configurazione esistente.

```php theme={null}
use Acme\Courier\Http\Middleware\AddCourierHeader;
use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(append: [
        AddCourierHeader::class,
    ]);
})
```

Questa configurazione usa direttamente il nome della classe, quindi non dipende dall'ordine di registrazione degli alias. L'ambito di applicazione è il gruppo `web`, non lo stack globale. Il middleware non viene applicato automaticamente ad `api` né alle route prive di entrambi i gruppi.

<Warning>
  Un design che applica il middleware all'intero gruppo `web` al momento dell'installazione del pacchetto e un design in cui è l'utente ad applicarlo esplicitamente non sono compatibili. Non estendere a tutte le route, tramite un aggiornamento automatico, elaborazioni che influiscono su autenticazione, sessioni, header di risposta, comunicazioni esterne e simili.
</Warning>

## Le operazioni sui gruppi del Router si comportano in modo diverso

Se il pacchetto fornisce un proprio gruppo, usa un nome specifico. L'esempio seguente va inserito nel `boot(Router $router)` del provider.

```php theme={null}
$router->middlewareGroup('acme-courier', [
    AddCourierHeader::class,
]);
```

L'utente può applicarlo con `->middleware('acme-courier')`. Tuttavia, questo gruppo contiene solo le classi indicate e non eredita le sessioni né la protezione CSRF di `web`.

Esistono anche API per aggiungere elementi a gruppi esistenti, ma nell'implementazione del Router `v13.36.0` presentano le differenze seguenti.

| Metodo del Router | Se il gruppo esiste | Se il gruppo non esiste |
| - | - | - |
| `middlewareGroup($name, $items)` | Sostituisce l'intero array | Lo crea con l'array indicato |
| `pushMiddlewareToGroup($name, $item)` | Aggiunge in coda se l'elemento non è già presente | Crea un array vuoto e poi aggiunge |
| `prependMiddlewareToGroup($name, $item)` | Aggiunge in testa se l'elemento non è già presente | Non fa nulla |

Se imposti solo la classe del pacchetto con `middlewareGroup('web', [...])`, sostituisci il contenuto esistente di `web`. Non confonderlo con i metodi di aggiunta. Inoltre, eseguire `pushMiddlewareToGroup()` su un gruppo `web` inesistente non ripristina il gruppo `web` predefinito.

Il controllo dei duplicati dei metodi di aggiunta si basa sui valori registrati. Un alias e un nome di classe che puntano alla stessa classe sono stringhe diverse, quindi nella tabella di registrazione risultano elementi distinti. Uniforma la notazione e non dare per scontato che, al momento della registrazione, vengano eliminati i duplicati della stessa classe scritta in modi diversi.

### Non affidarti al solo ordine di registrazione per garantire l'ordine di esecuzione

Il Router espande gli alias e i gruppi dei middleware assegnati alla route, gestisce le esclusioni e poi ordina in base alla priorità. La sola aggiunta in testa o in coda non garantisce un ordine rigoroso rispetto all'autenticazione o al route model binding.

Inoltre, `syncMiddlewareToRouter()` dell'HTTP Kernel sincronizza nel Router i gruppi del Kernel tramite `middlewareGroup()`. Se la configurazione del Kernel viene risincronizzata in seguito, il contenuto dei gruppi aggiunto direttamente al Router può essere sostituito. Invece di competere sulla modifica dei gruppi esistenti in base all'ordine di avvio dei pacchetti, adotta come regola di base la centralizzazione della configurazione nel `withMiddleware()` dell'applicazione che utilizza il pacchetto.

Per le funzionalità che richiedono un ordine preciso, ad esempio dopo l'avvio della sessione o dopo l'autenticazione, indica chiaramente questo presupposto nelle istruzioni di installazione e verificalo insieme alla configurazione delle priorità dell'applicazione. Evita che il pacchetto sostituisca per intero l'elenco delle priorità dell'applicazione.

## Confini tra cache e verifica

Non inserire la registrazione degli alias all'interno della condizione `routesAreCached()` o nel file delle route. Quando esiste la cache, `loadRoutesFrom()` non carica il file delle route, ma la registrazione resta necessaria per risolvere in fase di esecuzione gli alias presenti nelle route in cache. Registrali ogni volta nel `boot()` del provider.

Se modifichi l'assegnazione alle route, ricrea la cache delle route nell'applicazione che utilizza il pacchetto.

```bash theme={null}
php artisan route:cache
php artisan route:list --path=courier-status -vv
```

`-vv` serve a espandere e verificare il contenuto dei gruppi. Tuttavia, la riuscita della visualizzazione dell'elenco non garantisce il funzionamento della logica interna al middleware né l'uso della sessione. Servono anche test delle richieste HTTP.

Quello che segue è un metodo da aggiungere al Feature test di un'applicazione Laravel che definisce la route `/courier-status` vista sopra.

```php theme={null}
public function test_courier_header_is_applied(): void
{
    $this->get('/courier-status')
        ->assertOk()
        ->assertHeader('X-Acme-Courier', 'enabled');
}
```

| Caso da verificare | Risultato atteso |
| - | - |
| Route con il solo alias registrato | L'header non viene aggiunto |
| Route a cui è assegnato l'alias | L'header viene aggiunto |
| Route a cui è assegnato direttamente il nome della classe | Stesso comportamento |
| Avvio di una nuova applicazione dopo la creazione della cache | Stesso comportamento sulla stessa route |
| Scelta dell'applicazione all'intero gruppo `web` | Viene applicato alle route `web` interessate e non si estende alle altre |
| Gruppi e priorità personalizzati nell'applicazione che usa il pacchetto | L'ordine rispetto a sessione, autenticazione e binding soddisfa i requisiti |

I test unitari che controllano l'esistenza dei gruppi o l'array degli alias e l'esecuzione HTTP reale sono verifiche distinte. In particolare, la verifica della cache non va fatta solo osservando il Router dello stesso processo, ma con un nuovo avvio dopo la creazione della cache. Se usi worker di lunga durata, ricaricali seguendo la normale procedura di deploy.

## Pagine correlate

<Columns cols={2}>
  <Card title="Middleware" icon="layer-group" href="/it/middleware">
    Ripassa le basi di creazione, applicazione alle route, parametri e priorità.
  </Card>

  <Card title="Registrazione e cache delle route dei pacchetti" icon="route" href="/it/advanced/package-routes">
    Approfondisce il rapporto tra il caricamento delle route e la configurazione al momento della creazione della cache.
  </Card>
</Columns>

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: Middleware](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/middleware.md)
* [Documentazione ufficiale di Laravel: boot dei service provider e dependency injection](https://github.com/laravel/docs/blob/6bb0a3be3c623f7964c8277625a07b6df7f1de2e/providers.md#the-boot-method)
* [Router: registrazione degli alias, operazioni sui gruppi, espansione e ordinamento dei middleware](https://github.com/laravel/framework/blob/v13.36.0/src/Illuminate/Routing/Router.php)
* [HTTP Kernel: syncMiddlewareToRouter](https://github.com/laravel/framework/blob/v13.36.0/src/Illuminate/Foundation/Http/Kernel.php)


## Related topics

- [Registrazione e cache delle route di un pacchetto](/it/advanced/package-routes.md)
- [Registrazione e cache dei listener di eventi di un pacchetto](/it/advanced/package-events.md)
- [Registrazione dei comandi Artisan di un pacchetto e risoluzione delle dipendenze](/it/advanced/package-commands.md)
- [Progettare il ciclo di vita dei servizi di un pacchetto](/it/advanced/package-service-lifetimes.md)
- [Argomenti avanzati](/it/advanced/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.