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

# Cache dei pacchetti e integrazione con optimize

> Usa optimizes() di Laravel 13 per integrare nel deploy la generazione e l'eliminazione della cache specifica di un pacchetto. Partendo dall'implementazione, scopri chiavi di registrazione, esclusioni, ordine di esecuzione e codici di uscita in caso di errore.

Se il tuo pacchetto pregenera metadati propri, chiedere agli utenti di aggiungere un comando dedicato alla loro procedura di deploy rende facile dimenticarlo durante gli aggiornamenti. Con `ServiceProvider::optimizes()` puoi integrare i comandi di generazione ed eliminazione in `optimize` e `optimize:clear` di Laravel.

Questa pagina presuppone le [basi dello sviluppo di pacchetti](/it/advanced/package-development) ed esamina l'implementazione di Laravel Framework `v13.35.0`. Non tratta il formato dei file di cache, ma il contratto di registrazione e di gestione operativa.

## Separare la registrazione dei comandi da quella dei task

`commands()` registra le classi di comando richiamabili da Artisan. `optimizes()` è un'operazione distinta, che registra come task di ottimizzazione nomi di comandi già eseguibili. Chiamare solo quest'ultimo non registra le classi di comando.

L'esempio seguente presuppone che il pacchetto implementi già `CacheMetadataCommand` e `ClearMetadataCommand`, con `$signature` rispettivamente `courier:cache` e `courier:clear-cache`.

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

namespace Acme\Courier;

use Acme\Courier\Console\Commands\CacheMetadataCommand;
use Acme\Courier\Console\Commands\ClearMetadataCommand;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            $this->commands([
                CacheMetadataCommand::class,
                ClearMetadataCommand::class,
            ]);

            $this->optimizes(
                optimize: 'courier:cache',
                clear: 'courier:clear-cache',
                key: 'acme-courier',
            );
        }
    }
}
```

Tutti gli argomenti di `optimizes()` sono nullable, quindi puoi registrare anche solo la generazione o solo l'eliminazione. In ogni caso, indica sempre agli utenti con quale procedura invalidare la cache generata.

## Anche la chiave di registrazione è un contratto con gli utenti

`ServiceProvider` salva i comandi di generazione nell'array statico `$optimizeCommands` e quelli di eliminazione in `$optimizeClearCommands`. In entrambi i casi la `key` diventa la chiave dell'array.

Se ometti `key`, il nome viene generato dal nome della classe del provider. Per esempio, `CourierServiceProvider` diventa `courier`. Poiché viene usato solo il nome della classe, possono verificarsi collisioni anche con provider omonimi in namespace diversi.

Se registri di nuovo la stessa chiave, il comando di quel lato viene sovrascritto dal valore successivo. Se vuoi registrare più task, specifica chiavi diverse. Evita inoltre le chiavi dei task standard di Laravel, come `config` o `routes`: quando i task standard e quelli dei pacchetti vengono uniti, le chiavi stringa identiche vengono sovrascritte.

<Tip>
  Specifica esplicitamente una chiave che identifichi il pacchetto, come `acme-courier`, e mantienila invariata tra una release e l'altra. La chiave diventa il nome visualizzato del task ed è anche il valore che gli utenti indicano con `--except`.
</Tip>

## Esecuzione dopo i task standard

Nell'implementazione esaminata, entrambi i comandi espandono l'array dei pacchetti registrati nell'array dei task standard e poi li richiamano in sequenza. Se usi una chiave che non va in collisione, i task del pacchetto vengono aggiunti dopo quelli standard.

| Comando | Ordine di esecuzione dei task standard | Elaborazione successiva |
| - | - | - |
| `optimize` | `config:cache` → `event:cache` → `route:cache` → `view:cache` | Comandi di generazione registrati |
| `optimize:clear` | `config:clear` → `cache:clear` → `clear-compiled` → `event:clear` → `route:clear` → `view:clear` | Comandi di eliminazione registrati |

```mermaid theme={null}
flowchart TD
    A["boot() del provider"] --> B["Registrazione dei comandi Artisan con commands()"]
    A --> C["Registrazione di chiave e nomi dei comandi con optimizes()"]
    B --> D["php artisan optimize"]
    C --> D
    D --> E["Cache standard di configurazione, eventi, route e viste"]
    E --> F["Esecuzione di courier:cache"]
    C --> G["php artisan optimize:clear"]
    G --> H["Eliminazione delle cache standard"]
    H --> I["Esecuzione di courier:clear-cache"]
```

Tenendo conto di quest'ordine, il comando di generazione non deve ricostruire le altre cache standard, ma generare solo i dati di proprietà del pacchetto. Non usare `optimizes()` come API per controllare le dipendenze di ordine tra più pacchetti: se ti serve un ordine rigoroso, elenca esplicitamente i comandi dedicati.

<Warning>
  `optimize:clear` include anche `cache:clear` ed elimina i dati dello store di cache predefinito. Se vuoi eliminare solo la cache specifica del pacchetto, esegui direttamente `courier:clear-cache`. Progetta anche il comando di eliminazione del pacchetto in modo che non svuoti l'intero store condiviso, ma elimini solo le chiavi o i file di sua proprietà.
</Warning>

## Esclusione per chiave o per nome del comando

L'opzione `--except` di entrambi i comandi accetta valori separati da virgole. Rimuove gli spazi iniziali e finali di ciascun valore ed esclude i task la cui chiave o il cui nome di comando corrisponde.

```bash theme={null}
php artisan optimize --except=acme-courier
php artisan optimize --except=courier:cache
php artisan optimize:clear --except=acme-courier,cache
```

I primi due escludono lo stesso task di generazione. Il terzo esclude il task di eliminazione del pacchetto e il `cache:clear` standard. `cache` è la chiave di un task, non un nome specifico del pacchetto.

L'esclusione vale solo per quell'esecuzione. Non è un'impostazione che disattiva la registrazione nel provider né che elimina automaticamente una cache del pacchetto creata in precedenza.

## Distinguere il FAIL di un task dal codice di uscita del comando padre

`OptimizeCommand` e `OptimizeClearCommand` richiamano ciascun task con `callSilently()` e passano alla visualizzazione del task l'informazione se il codice di uscita è `0`. Poiché l'output normale dei comandi figli non viene mostrato, per indagare sulla causa esegui direttamente il comando dedicato.

In Laravel `v13.35.0`, i metodi `handle()` di entrambi i comandi non restituiscono come valore di ritorno del padre il valore diverso da zero di un comando figlio. Anche se a schermo compare `FAIL`, il ciclo prosegue e, in assenza di eccezioni, il codice di uscita del comando padre è `0`. Le eccezioni lanciate, invece, vengono rilanciate dal componente di visualizzazione dei task, quindi il comportamento non è lo stesso.

<Warning>
  Non considerare riuscita la generazione della cache del pacchetto solo perché `php artisan optimize` è terminato con codice di uscita `0`. Questo comportamento si basa sull'implementazione della versione esaminata, quindi verificalo di nuovo quando aggiorni le versioni di Laravel supportate.
</Warning>

Se la generazione del pacchetto è un requisito obbligatorio del deploy, usa una procedura in cui puoi controllare direttamente il codice di uscita del comando figlio. Per esempio, il codice seguente esclude il task del pacchetto dall'esecuzione complessiva e lo esegue direttamente una sola volta dopo i task standard.

```bash theme={null}
php artisan optimize --except=acme-courier && php artisan courier:cache
```

Questo esempio riflette nel codice di uscita il fallimento di `courier:cache`, ma non aggrega le uscite con valore diverso da zero dei task standard. Nei deploy in cui devi rilevare rigorosamente anche quelle, esegui singolarmente i comandi necessari e controlla i rispettivi codici di uscita.

## Progettare e verificare una cache che regga agli aggiornamenti

Oltre alla registrazione, definisci anche le responsabilità dei comandi e del codice che legge la cache.

* La generazione, anche se eseguita più volte, porta allo stesso stato a partire dallo stesso input e non attiva dati incompleti in caso di errore a metà.
* L'eliminazione termina correttamente anche se la cache non esiste e non elimina la configurazione pubblicata né i dati persistenti degli utenti.
* Un comando di generazione che fallisce segnala l'errore e restituisce un valore diverso da zero. Anche il codice di lettura non deve trattare incondizionatamente come valida una cache corrotta.
* Se modifichi il formato della cache, informa gli utenti della necessità di rigenerarla e valuta anche il riavvio dei processi a lunga esecuzione.

Oltre ai test del pacchetto, nell'applicazione che lo usa verifica quanto segue. Poiché gli array di registrazione sono statici, fai attenzione anche allo stato di registrazione che persiste tra test nello stesso processo.

| Operazione da verificare | Condizione di completamento |
| - | - |
| Eseguire direttamente i comandi dedicati di generazione ed eliminazione | `0` in caso di successo, valore diverso da zero se la generazione fallisce. L'eliminazione riesce anche se eseguita due volte |
| Eseguire `optimize` / `optimize:clear` | I task del pacchetto vengono richiamati una volta ciascuno e lo stato dopo generazione ed eliminazione è corretto |
| Specificare `--except` con la chiave e con il nome del comando | Solo il task interessato non viene eseguito |
| Far terminare il comando di generazione con un valore diverso da zero | Puoi distinguere la visualizzazione di `FAIL` dal codice di uscita del comando padre nella versione esaminata |
| Rigenerare dopo l'aggiornamento del pacchetto | La cache viene generata con il nuovo codice e la nuova configurazione e il vecchio formato non continua a essere letto |

## Pagine correlate

<Columns cols={2}>
  <Card title="Merge e cache della configurazione dei pacchetti" icon="sliders" href="/it/advanced/package-config-merging">
    Scopri come si integra la configurazione pubblicata e il rapporto con la ricostruzione della cache della configurazione.
  </Card>

  <Card title="Testare pacchetti Laravel con Orchestra Testbench" icon="flask" href="/it/advanced/package-testing">
    Registra provider e comandi Artisan nell'ambiente di test.
  </Card>
</Columns>

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: Optimize commands](https://github.com/laravel/docs/blob/13.x/packages.md#optimize-commands)
* [ServiceProvider: optimizes() e chiavi di registrazione](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Support/ServiceProvider.php)
* [OptimizeCommand: task ed esclusioni](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/OptimizeCommand.php)
* [OptimizeClearCommand: task di eliminazione e ordine di esecuzione](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/OptimizeClearCommand.php)
* [Command: valore di ritorno di handle() e codice di uscita](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Console/Command.php)
* [Task: visualizzazione del risultato e rilancio delle eccezioni](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Console/View/Components/Task.php)


## Related topics

- [Sviluppo di pacchetti Laravel](/it/advanced/package-development.md)
- [Argomenti avanzati](/it/advanced/index.md)
- [Merge e cache della configurazione dei pacchetti](/it/advanced/package-config-merging.md)
- [I miei pacchetti](/it/packages/index.md)
- [Struttura interna del package auto-discovery](/it/advanced/package-discovery.md)


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