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

# Aggiungere informazioni diagnostiche del pacchetto ad about

> Come usare AboutCommand di Laravel 13 per mostrare lo stato della configurazione del pacchetto in CLI e in JSON, con il momento di valutazione e gli aspetti da considerare per la manutenzione a lungo termine.

Quando un utente ti contatta per assistenza, è utile poter verificare in un formato uniforme se il pacchetto è abilitato o disabilitato e quale driver è selezionato. Con `AboutCommand::add()` puoi aggiungere una sezione dedicata al pacchetto all'output di `php artisan about` senza implementare un comando apposito.

La documentazione ufficiale contiene un esempio di base della registrazione. Questa pagina esamina l'implementazione di Laravel 13 e approfondisce il momento in cui vengono raccolte le informazioni, i tipi JSON, le collisioni tra nomi di sezione e lo stato della registrazione nei test.

## Registrare il contenuto da mostrare nel provider

L'esempio seguente presuppone che `courier.enabled` e `courier.driver` siano già registrati come configurazione del pacchetto. Per sapere come registrare la configurazione, consulta [Merge e cache della configurazione dei pacchetti](/it/advanced/package-config-merging).

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

namespace Acme\Courier;

use Illuminate\Foundation\Console\AboutCommand;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if (! $this->app->runningInConsole()) {
            return;
        }

        AboutCommand::add('Acme Courier', fn () => [
            'Enabled' => AboutCommand::format(
                (bool) config('courier.enabled', false),
                console: fn (bool $enabled) => $enabled ? 'ENABLED' : 'OFF',
            ),
            'Driver' => (string) config('courier.driver', 'log'),
        ]);
    }
}
```

`runningInConsole()` è una condizione che evita registrazioni inutili durante le richieste HTTP. Non verifica solo l'esecuzione di `about`: la registrazione avviene anche con gli altri comandi Artisan. Tuttavia, la lettura della configurazione all'interno della closure qui sopra non viene eseguita al momento della registrazione.

<Warning>
  Scegli esplicitamente le voci da mostrare. Non stampare chiavi API, token di accesso, URL di connessione contenenti credenziali o interi array di configurazione. Nemmeno l'output JSON maschera automaticamente le informazioni riservate. In caso di richiesta di assistenza, chiedi all'utente di condividere solo la sezione del pacchetto e di controllarne il contenuto prima di inviarla.
</Warning>

## Distinguere il momento della registrazione da quello della valutazione

In Laravel `v13.35.0`, `add()` non raccoglie i dati subito, ma aggiunge una closure di registrazione all'array statico `$customDataResolvers`. All'esecuzione di `about` vengono assemblati i dati da mostrare e valutate le closure di recupero dati registrate.

```mermaid theme={null}
flowchart TD
    A["boot() del provider"] --> B["add() salva la registrazione"]
    B --> C["Esecuzione di about"]
    C --> D["Raccolta delle informazioni standard e delle sezioni aggiunte"]
    D --> E["Valutazione delle closure di recupero dati"]
    E --> F["Filtro delle sezioni con --only"]
    F --> G["Visualizzazione in CLI o JSON"]
```

Leggere i valori di configurazione dentro la closure permette di riflettere lo stato al momento dell'esecuzione del comando, invece di leggerli in anticipo fuori da `add()` e fissarli in un array. D'altra parte, il filtro `--only` viene applicato **dopo** la valutazione delle closure di recupero dati.

```bash theme={null}
php artisan about --only=environment
```

Anche specificando solo una sezione standard come in questo caso, la closure `Acme Courier` qui sopra viene valutata. Non essere mostrato e non essere eseguito sono due cose diverse.

Per questo motivo, le informazioni aggiuntive vanno ricavate da valori di configurazione o da uno stato locale leggero. Se inserisci verifiche di connettività verso API esterne, query al database o modifiche di file, anche i comandi che consultano sezioni non correlate possono diventare lenti o fallire. Sposta verifiche di connettività e riparazioni in comandi Artisan dedicati.

<Tip>
  La sola condizione `runningInConsole()` non garantisce che il `boot()` di un service provider differito venga eseguito. Se vuoi che le informazioni diagnostiche siano sempre registrate, colloca la registrazione in un provider caricato immediatamente. Per una configurazione in cui solo i binding dei servizi sono differiti, consulta [Service provider differiti](/it/advanced/deferred-provider).
</Tip>

## Conciliare la visualizzazione CLI con i tipi JSON

Per vedere solo le informazioni del pacchetto, specifica il nome della sezione convertito in minuscolo e in snake case. Per `Acme Courier` il valore è `acme_courier`.

```bash theme={null}
php artisan about --only=acme_courier
php artisan about --only=environment,acme_courier
php artisan about --only=acme_courier --json
```

Con l'esempio di registrazione qui sopra, quando `courier.enabled` è `true` e `courier.driver` è `log`, il JSON ha la forma seguente.

```json theme={null}
{
  "acme_courier": {
    "enabled": true,
    "driver": "log"
  }
}
```

In CLI, `Enabled` viene mostrato come `ENABLED`. `AboutCommand::format()` è un helper che permette di specificare `console` per la CLI e `json` per il JSON. L'esempio qui sopra specifica solo `console`, quindi in JSON viene restituito il valore booleano originale. Non è necessario riutilizzare nel JSON la stringa mostrata in CLI.

| Ambito | Conversione ed elaborazione nell'implementazione |
| - | - |
| Valore di `--only` e nome della sezione | Confrontati dopo la conversione in minuscolo e poi in snake case |
| Chiave della sezione JSON | Nome della sezione convertito in snake case |
| Chiave della voce JSON | Nome della voce convertito in minuscolo e poi in snake case |
| Valore di `format()` | `console` in CLI, `json` in JSON. Valore originale se non specificato |

Usare, come nell'esempio, nomi composti da normali parole inglesi separate da spazi rende più semplice gestire filtri e chiavi JSON. Le chiavi usate dai processi automatici possono cambiare anche modificando il nome visualizzato, quindi verifica la compatibilità a ogni rilascio.

## Usare nomi di sezione specifici del pacchetto

`add()` aggiunge voci alla stessa sezione. Specificare una sezione con lo stesso nome non sostituisce l'intero contenuto registrato in precedenza.

Scegli un nome che si distingua dagli altri pacchetti, come `Acme Courier`, e limita le aggiunte alle sezioni standard di Laravel `Environment`, `Cache`, `Drivers` e `Storage` ai casi in cui sono necessarie.

Se registri più volte una voce con lo stesso nome nella stessa sezione, in CLI possono restare più righe, mentre in JSON vengono raggruppate sotto la stessa chiave e resta l'ultimo valore. Evita anche nomi che, pur scritti in modo diverso, diventano la stessa chiave dopo la conversione in snake case. Concentra la registrazione in un unico punto e progetta le voci in modo che siano univoche sia in CLI sia in JSON.

## Gestire lo stato di registrazione statico nei test

All'inizio dell'esecuzione di `about` i dati da mostrare `$data` vengono reinizializzati, ma l'elenco delle registrazioni di informazioni aggiuntive `$customDataResolvers` viene mantenuto. In questo modo le informazioni possono essere raccolte di nuovo ogni volta dalle stesse registrazioni, ma se il `boot()` del provider viene ripetuto nello stesso processo PHP le registrazioni possono accumularsi.

`AboutCommand::flushState()` è un metodo che cancella **le registrazioni di tutti i pacchetti** e i dati da mostrare. Non chiamarlo nel provider di produzione per evitare duplicati nella tua sezione: perderesti anche le informazioni diagnostiche degli altri pacchetti.

Se ricostruisci l'applicazione con una tua infrastruttura di test, stabilisci a chi spetta reinizializzare lo stato tra un test e l'altro. Se lo reinizializzi, fallo prima di avviare il provider interessato ed esegui poi tutte le registrazioni necessarie. Verifica anche se l'infrastruttura di test esistente reinizializza già lo stato.

### Verifiche prima del rilascio

Verifica le seguenti combinazioni con [Testare pacchetti Laravel con Orchestra Testbench](/it/advanced/package-testing) e in un'applicazione reale che usa il pacchetto.

| Operazione da verificare | Risultato atteso |
| - | - |
| `about --only=acme_courier` | Viene mostrata solo la sezione del pacchetto, senza voci duplicate |
| `about --only=acme_courier --json` | `enabled` si ottiene come boolean e `driver` come string |
| `about --only=environment` | La raccolta delle informazioni del pacchetto non comporta comunicazioni esterne né effetti collaterali e il comando termina normalmente |
| Modifica di abilitazione o driver | I valori mostrati e quelli JSON corrispondono alla configurazione al momento dell'esecuzione del comando |
| Due esecuzioni nella stessa applicazione | Le voci non si accumulano e le informazioni vengono raccolte di nuovo a ogni esecuzione |
| Ricostruzione dell'applicazione nello stesso processo PHP | Lo stato di registrazione non trapela tra i test e le informazioni degli altri pacchetti non vanno perse |
| Con la cache della configurazione presente | Vengono mostrati i valori di configurazione usati dall'applicazione, non il contenuto del file di configurazione pubblicato |

## Pagine correlate

<Columns cols={2}>
  <Card title="Sviluppo di pacchetti Laravel" icon="box" href="/it/advanced/package-development">
    Ripassa le basi dei provider e della registrazione delle risorse.
  </Card>

  <Card title="Merge e cache della configurazione dei pacchetti" icon="sliders" href="/it/advanced/package-config-merging">
    Scopri la relazione tra valori predefiniti, override degli utenti e cache della configurazione.
  </Card>
</Columns>

## Fonti primarie consultate

* [Documentazione ufficiale di Laravel: aggiungere informazioni ad about da un pacchetto](https://github.com/laravel/docs/blob/13.x/packages.md#about-artisan-command)
* [Documentazione ufficiale di Laravel: about e --only](https://github.com/laravel/docs/blob/13.x/configuration.md#the-about-command)
* [Laravel Framework v13.35.0: AboutCommand](https://github.com/laravel/framework/blob/v13.35.0/src/Illuminate/Foundation/Console/AboutCommand.php): registrazione, ordine di valutazione, conversione delle chiavi, `format()`, `flushState()`.
* [Laravel Framework v13.35.0: test di format](https://github.com/laravel/framework/blob/v13.35.0/tests/Foundation/Console/AboutCommandTest.php)
* [Laravel Framework v13.35.0: test di integrazione dell'output JSON](https://github.com/laravel/framework/blob/v13.35.0/tests/Integration/Foundation/Console/AboutCommandTest.php)


## Related topics

- [Sviluppo di pacchetti Laravel](/it/advanced/package-development.md)
- [Pacchetto core e driver personalizzati - Feedable](/it/packages/feedable/core.md)
- [Analisi statica dei pacchetti (PHPStan / Larastan)](/it/advanced/package-static-analysis.md)
- [Presentazione del pacchetto Blaze](/it/blog/blaze-introduction.md)
- [Il nuovo ecosistema di analisi del codice Laravel — surveyor / ranger / roster](/it/blog/laravel-ecosystem-analysis.md)


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