Registrazione e cache delle route di un pacchetto

Quando un pacchetto fornisce endpoint HTTP, non basta che le route funzionino nell’ambiente di sviluppo: devono rispettare lo stesso contratto anche dopo che l’applicazione che le usa ha creato la cache delle route. Se il design permette di modificare tramite configurazione il prefisso degli URL o l’attivazione delle route, occorre anche indicare agli utenti quando quelle modifiche diventano effettive. Questa pagina presuppone le basi dello sviluppo di pacchetti e tratta separatamente il processo di registrazione e il ciclo di vita della cache. La documentazione ufficiale di riferimento è quella del branch predefinito di Laravel 13, 13.x, mentre per l’implementazione del framework si fa riferimento all’ultima release, v13.34.0.

loadRoutesFrom si limita a caricare il file

ServiceProvider::loadRoutesFrom() non carica il file di route se l’applicazione implementa CachesRoutes e routesAreCached() restituisce true. Negli altri casi esegue il require del file indicato. Il metodo in sé non aggiunge prefissi di URI o di nome delle route, namespace dei controller né middleware. Non pubblica nemmeno file e non aggiunge route a una cache esistente. Il diagramma presuppone un’applicazione Laravel standard. Non esiste una cache dedicata al pacchetto: le route del pacchetto sono incluse nella cache delle route dell’intera applicazione.

Chiamare routes/web.php il file all’interno del pacchetto non basta ad applicare il middleware web. Il percorso di caricamento è diverso da quello dei file di route standard dell’applicazione, quindi specifica esplicitamente nel pacchetto i middleware necessari.

Separare configurazione e registrazione

Nell’esempio seguente creiamo un endpoint pubblico che indica se il pacchetto è in grado di rispondere. Si presuppone che il PSR-4 di Composer mappi Acme\Courier\ su src/ e che il provider sia registrato tramite auto-discovery o manualmente.

config/courier.php

<?php

return [
    'routes' => [
        'enabled' => true,
        'prefix' => 'acme-courier',
    ],
];

Il merge della configurazione avviene in register(), il caricamento delle route in boot(). Non rendere DeferrableProvider un provider che registra route HTTP: non ci sarebbe più la garanzia che il provider venga avviato nel momento in cui le route servono.

src/CourierServiceProvider.php

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->mergeConfigFrom(__DIR__.'/../config/courier.php', 'courier');
    }

    public function boot(): void
    {
        if (config('courier.routes.enabled')) {
            $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        }
    }
}

Questa condizione controlla solo la registrazione delle route. In un provider che registra anche altri servizi o view, non inserire quelle registrazioni all’interno della condizione. Per la pubblicazione della configurazione agli utenti e le avvertenze sul merge di configurazioni annidate, consulta Merge e cache della configurazione dei pacchetti.

routes/web.php

<?php

use Acme\Courier\Http\Controllers\StatusController;
use Illuminate\Support\Facades\Route;

Route::middleware('web')
    ->prefix(config('courier.routes.prefix'))
    ->name('acme-courier.')
    ->group(function () {
        Route::get('/status', StatusController::class)->name('status');
    });

src/Http/Controllers/StatusController.php

<?php

namespace Acme\Courier\Http\Controllers;

use Illuminate\Http\JsonResponse;

class StatusController
{
    public function __invoke(): JsonResponse
    {
        return response()->json(['available' => true]);
    }
}

L’URI predefinito è /acme-courier/status e il nome della route è acme-courier.status. Se generi l’URL con route('acme-courier.status'), il codice chiamante può continuare a usare lo stesso nome di route anche quando il prefisso dell’URI cambia. Il name() del gruppo concatena le stringhe così come sono, quindi specifica anche il . finale.

web non sostituisce autenticazione e autorizzazione. Questo esempio è un endpoint pubblico che non contiene informazioni riservate. Per gli endpoint che restituiscono dati degli utenti, prevedi separatamente middleware di autenticazione e logica di autorizzazione adeguati ai requisiti.

Prevenire separatamente i conflitti di URI e di nome delle route

Il prefisso dell’URI e il prefisso del nome delle route sono meccanismi distinti. Aggiungerne solo uno non impedisce i conflitti dell’altro.

Elemento	Design di questo esempio	Attenzione in fase di manutenzione
URI	`acme-courier` come valore predefinito, modificabile da configurazione	Scegliere un valore che non entri in conflitto con gli URL esistenti dell’applicazione
Nome della route	`acme-courier.` fisso	Usare un nome specifico del pacchetto e mantenerlo come contratto per la generazione degli URL
Controller	Uso del riferimento alla classe	Non dipendere dal namespace dei controller dell’applicazione
Middleware	`web` specificato esplicitamente	Verificarlo insieme alla configurazione dei middleware dell’applicazione di destinazione

Quando crea la collezione di route per la cache, AbstractRouteCollection lancia una LogicException se lo stesso nome è assegnato a route diverse. Il fatto che “con un avvio normale l’URL viene generato” non garantisce che le route siano memorizzabili in cache. Anche due route con URI diversi creano problemi se hanno lo stesso nome. Non usare come meccanismo di estensione del pacchetto la sovrascrittura delle route dell’applicazione in base all’ordine di registrazione. Se necessario, fornisci un’impostazione per disattivare le route e un servizio che gli utenti possano chiamare da route proprie.

La configurazione al momento della creazione della cache resta nelle definizioni delle route

RouteCacheCommand esegue prima route:clear, poi avvia una nuova applicazione e raccoglie le route. Prepara quelle route in una forma serializzabile e scrive il risultato compilato nel file di cache. In questa fase viene caricato anche il file di route del pacchetto, quindi il prefisso e la registrazione o meno delle route dipendono dalla configurazione al momento della creazione della cache. Negli avvii successivi loadRoutesFrom() non carica il file e vengono usate le route in cache.

Modifica	Se resta una vecchia cache delle route	Azione necessaria
Aggiunta di route al pacchetto	Le route aggiunte non compaiono	Ricreare la cache delle route
Modifica di `routes.prefix`	Resta l’URI originale	Ricrearla con la nuova configurazione
Impostazione di `routes.enabled` a `false`	Le route presenti in cache non scompaiono	Ricrearla con la configurazione disattivata
Rimozione del pacchetto	Possono restare definizioni che fanno riferimento a classi rimosse	Ricrearla con la configurazione successiva alla rimozione

routes.enabled è un’impostazione che controlla la registrazione, non un rifiuto dell’accesso per singola richiesta. Se resta una vecchia cache, disattivare solo l’impostazione non significa aver disattivato l’endpoint.

Non registrare le route in base a condizioni che cambiano a ogni richiesta, come l’utente o il tenant. Quelle condizioni vengono valutate nell’ambiente CLI al momento della creazione della cache. Registra le route con una configurazione stabile e decidi se consentire l’accesso tramite middleware o autorizzazione nel controller.

Nel deploy, definisci prima la configurazione

Dopo aver aggiornato codice e configurazione, nelle configurazioni che usano la cache della configurazione ricrea le cache nell’ordine seguente. Includi questi passaggi nel processo di deploy dell’applicazione che usa il pacchetto.

php artisan config:cache
php artisan route:cache
php artisan route:list --name=acme-courier -vv

Se esegui route:cache mentre resta una vecchia cache della configurazione, anche le route vengono create con la vecchia configurazione. Rieseguire solo config:cache non aggiorna la cache delle route. Con -vv puoi verificare anche il contenuto dei gruppi di middleware. Per verificare il comportamento senza cache durante lo sviluppo, cancella entrambe le cache se necessario.

php artisan config:clear
php artisan route:clear

Il file di route non viene eseguito negli avvii in cui esiste la cache. Registrare lì event listener o binding del container cambierebbe il comportamento, quindi evita che abbia effetti collaterali diversi dalla definizione delle route. Negli ambienti che usano processi di lunga durata, includi nella normale procedura di deploy anche il ricaricamento dopo l’aggiornamento della cache.

Combinazioni da verificare prima del rilascio

Oltre ai test del pacchetto, verifica le seguenti combinazioni in un’applicazione Laravel 13 che lo usa. Non limitarti alla registrazione delle route in memoria: includi anche il percorso in cui Artisan avvia una nuova applicazione.

Senza cache, /acme-courier/status risponde e il nome della route e i middleware sono quelli previsti.
route:cache va a buon fine e anche in un nuovo avvio la route risponde con lo stesso URI e lo stesso nome.
Modificando il prefisso e ricreando la cache, il nuovo URI risponde e la route del pacchetto sul vecchio URI scompare.
Disattivando le route e ricreando la cache, la route non compare in route:list --name=acme-courier.
URI e nomi delle route non entrano in conflitto con l’applicazione o con altri pacchetti.

Verificando anche il caso in cui resta una vecchia cache, puoi riprodurre segnalazioni degli utenti come “ho modificato il file di configurazione ma l’URL non cambia”. Indica esplicitamente la ricreazione della cache nelle istruzioni di aggiornamento e considera anche le modifiche ai nomi delle route e ai middleware nella valutazione della compatibilità.

Pagine correlate

Routing

Le basi di gruppi di route, route con nome e visualizzazione dell’elenco.

Merge e cache della configurazione dei pacchetti

Una procedura di aggiornamento che tiene conto della configurazione pubblicata e della cache della configurazione.

Service provider differiti

Perché non rendere differito un provider che registra route.

Gestire la compatibilità tra versioni dei pacchetti

Collega le modifiche all’API pubblica alla politica di rilascio e alla verifica continua.

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 cache delle route di un pacchetto

loadRoutesFrom si limita a caricare il file

Separare configurazione e registrazione

Prevenire separatamente i conflitti di URI e di nome delle route

La configurazione al momento della creazione della cache resta nelle definizioni delle route

Nel deploy, definisci prima la configurazione

Combinazioni da verificare prima del rilascio

Pagine correlate

Routing

Merge e cache della configurazione dei pacchetti

Service provider differiti

Gestire la compatibilità tra versioni dei pacchetti

Fonti primarie consultate

​loadRoutesFrom si limita a caricare il file

​Separare configurazione e registrazione

​Prevenire separatamente i conflitti di URI e di nome delle route

​La configurazione al momento della creazione della cache resta nelle definizioni delle route

​Nel deploy, definisci prima la configurazione

​Combinazioni da verificare prima del rilascio

​Pagine correlate

Routing

Merge e cache della configurazione dei pacchetti

Service provider differiti

Gestire la compatibilità tra versioni dei pacchetti

​Fonti primarie consultate

loadRoutesFrom si limita a caricare il file

Separare configurazione e registrazione

Prevenire separatamente i conflitti di URI e di nome delle route

La configurazione al momento della creazione della cache resta nelle definizioni delle route

Nel deploy, definisci prima la configurazione

Combinazioni da verificare prima del rilascio

Pagine correlate

Fonti primarie consultate