Registrazione e ambito di applicazione dei middleware di un pacchetto

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

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.

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 o manualmente.

src/Http/Middleware/AddCourierHeader.php

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

src/CourierServiceProvider.php

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

routes/web.php

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

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.

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.

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.

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.

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

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.

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

Middleware

Ripassa le basi di creazione, applicazione alle route, parametri e priorità.

Registrazione e cache delle route dei pacchetti

Approfondisce il rapporto tra il caricamento delle route e la configurazione al momento della creazione della cache.

Sviluppo con AI

Design pattern

Sviluppo di pacchetti

Struttura dell'applicazione

Novità di Laravel 13

Approfondimento Eloquent

Estensione della validazione

Estensione dell'autenticazione

Sicurezza

Code

Test

Tempo reale

Registrazione e ambito di applicazione dei middleware di un pacchetto

Separare registrazione, applicazione ed esecuzione

Esporre l’alias dal provider

L’utente lo applica per singola route

L’applicazione all’intera applicazione è una scelta dell’utente

Le operazioni sui gruppi del Router si comportano in modo diverso

Non affidarti al solo ordine di registrazione per garantire l’ordine di esecuzione

Confini tra cache e verifica

Pagine correlate

Middleware

Registrazione e cache delle route dei pacchetti

Fonti primarie consultate

​Separare registrazione, applicazione ed esecuzione

​Esporre l’alias dal provider

​L’utente lo applica per singola route

​L’applicazione all’intera applicazione è una scelta dell’utente

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

​Non affidarti al solo ordine di registrazione per garantire l’ordine di esecuzione

​Confini tra cache e verifica

​Pagine correlate

Middleware

Registrazione e cache delle route dei pacchetti

​Fonti primarie consultate

Separare registrazione, applicazione ed esecuzione

Esporre l’alias dal provider

L’utente lo applica per singola route

L’applicazione all’intera applicazione è una scelta dell’utente

Le operazioni sui gruppi del Router si comportano in modo diverso

Non affidarti al solo ordine di registrazione per garantire l’ordine di esecuzione

Confini tra cache e verifica

Pagine correlate

Fonti primarie consultate