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

> Partendo dall'implementazione di Laravel 13, spiega il ruolo di loadRoutesFrom, la separazione tra middleware e nomi e la procedura per riflettere le modifiche alla configurazione nella cache delle route.

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](/it/advanced/package-development) 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.

```mermaid theme={null}
flowchart TD
    A["boot del provider"] --> B["Chiamata a loadRoutesFrom"]
    B --> C{"Esiste una cache delle route?"}
    C -->|No| D["require del file di route del pacchetto"]
    C -->|Sì| E["Salta il caricamento del file del pacchetto"]
    E --> F["Il RouteServiceProvider di Laravel<br>carica la cache dell'applicazione"]
```

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.

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

## 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](/it/advanced/package-discovery) o manualmente.

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

```php src/CourierServiceProvider.php theme={null}
<?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](/it/advanced/package-config-merging).

```php routes/web.php theme={null}
<?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');
    });
```

```php src/Http/Controllers/StatusController.php theme={null}
<?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.

<Info>
  `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.
</Info>

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

<Warning>
  `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.
</Warning>

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.

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

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

<Columns cols={2}>
  <Card title="Routing" icon="route" href="/it/routing">
    Le basi di gruppi di route, route con nome e visualizzazione dell'elenco.
  </Card>

  <Card title="Merge e cache della configurazione dei pacchetti" icon="sliders" href="/it/advanced/package-config-merging">
    Una procedura di aggiornamento che tiene conto della configurazione pubblicata e della cache della configurazione.
  </Card>

  <Card title="Service provider differiti" icon="clock" href="/it/advanced/deferred-provider">
    Perché non rendere differito un provider che registra route.
  </Card>

  <Card title="Gestire la compatibilità tra versioni dei pacchetti" icon="code-branch" href="/it/advanced/package-versioning">
    Collega le modifiche all'API pubblica alla politica di rilascio e alla verifica continua.
  </Card>
</Columns>

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: route dei pacchetti](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/packages.md#routes)
* [Documentazione ufficiale di Laravel: routing](https://github.com/laravel/docs/blob/156fc7fde114548640e13c39aa79b991291c3f91/routing.md)
* [ServiceProvider: implementazione di loadRoutesFrom](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Support/ServiceProvider.php)
* [RouteServiceProvider: caricamento della cache](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Support/Providers/RouteServiceProvider.php)
* [RouteCacheCommand: raccolta e salvataggio in una nuova applicazione](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Foundation/Console/RouteCacheCommand.php)
* [AbstractRouteCollection: rilevamento dei nomi di route duplicati](https://github.com/laravel/framework/blob/v13.34.0/src/Illuminate/Routing/AbstractRouteCollection.php)


## Related topics

- [Sviluppo di pacchetti Laravel](/it/advanced/package-development.md)
- [Argomenti avanzati](/it/advanced/index.md)
- [Pubblicazione e aggiornamento delle migrazioni di un pacchetto](/it/advanced/package-migrations.md)
- [Sovrascrivere e aggiornare le view di un pacchetto](/it/advanced/package-views.md)
- [Deployment](/it/deployment.md)


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