Aggiungere informazioni diagnostiche del pacchetto ad about

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.

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

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.

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

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.

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.

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.

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.

{
  "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 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

Sviluppo di pacchetti Laravel

Ripassa le basi dei provider e della registrazione delle risorse.

Merge e cache della configurazione dei pacchetti

Scopri la relazione tra valori predefiniti, override degli utenti e cache della configurazione.

Fonti primarie consultate

Documentazione ufficiale di Laravel: aggiungere informazioni ad about da un pacchetto
Documentazione ufficiale di Laravel: about e —only
Laravel Framework v13.35.0: AboutCommand: registrazione, ordine di valutazione, conversione delle chiavi, format(), flushState().
Laravel Framework v13.35.0: test di format
Laravel Framework v13.35.0: test di integrazione dell’output JSON

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

Aggiungere informazioni diagnostiche del pacchetto ad about

Registrare il contenuto da mostrare nel provider

Distinguere il momento della registrazione da quello della valutazione

Conciliare la visualizzazione CLI con i tipi JSON

Usare nomi di sezione specifici del pacchetto

Gestire lo stato di registrazione statico nei test

Verifiche prima del rilascio

Pagine correlate

Sviluppo di pacchetti Laravel

Merge e cache della configurazione dei pacchetti

Fonti primarie consultate

​Registrare il contenuto da mostrare nel provider

​Distinguere il momento della registrazione da quello della valutazione

​Conciliare la visualizzazione CLI con i tipi JSON

​Usare nomi di sezione specifici del pacchetto

​Gestire lo stato di registrazione statico nei test

​Verifiche prima del rilascio

​Pagine correlate

Sviluppo di pacchetti Laravel

Merge e cache della configurazione dei pacchetti

​Fonti primarie consultate

Registrare il contenuto da mostrare nel provider

Distinguere il momento della registrazione da quello della valutazione

Conciliare la visualizzazione CLI con i tipi JSON

Usare nomi di sezione specifici del pacchetto

Gestire lo stato di registrazione statico nei test

Verifiche prima del rilascio

Pagine correlate

Fonti primarie consultate