Skip to main content

Introduzione

laravel/doctor è il pacchetto ufficiale che diagnostica i problemi comuni di configurazione, ambiente e infrastruttura di un’applicazione Laravel. La versione v0.1.0 è stata rilasciata il 28 luglio 2026. Ogni diagnostic è un singolo controllo. Ad esempio verifica “Laravel può scrivere nella directory storage?” e riporta uno tra vari stati. Se il ripristino è sicuro e deterministico, viene offerta anche la correzione automatica; per problemi non correggibili automaticamente (come un fallimento della build degli asset) vengono suggeriti i passi di risoluzione (remediation).

Come eseguirlo

Dopo l’installazione viene registrato il comando Artisan doctor.
Quando trova problemi correggibili, Doctor segnala il problema e chiede conferma per la correzione.
Per applicare la correzione senza conferma usa l’opzione --fix.
Le correzioni standard coprono ripristini locali deterministici come: creazione del .env, generazione della APP_KEY, disattivazione della debug mode in produzione, aggiunta di .env al .gitignore, creazione di storage:link, ripristino dei permessi di scrittura sulle directory di storage.
Le funzioni di correzione sono disponibili solo per i formati di output CLI e agent. Nei formati JSON e report GitHub, --fix viene rifiutato per evitare che report leggibili dalle macchine modifichino l’applicazione.
Con --bail l’esecuzione si ferma al primo diagnostic con esito failure o error.

Stato dei diagnostic

Ogni diagnostic restituisce uno dei seguenti stati. Per default l’esecuzione termina con stato di errore in presenza di fail o error. Con --fail-on=warn fallisce anche per i warning; con --fail-on=never viene solo riportata la lista dei problemi.

Selezione dei diagnostic

Puoi selezionare o escludere diagnostic per nome classe, gruppo, pacchetto o wildcard di pacchetto.
Pubblicando il file di configurazione puoi impostare selezioni persistenti.

Modalità ambiente

La coda sync è un default ragionevole in sviluppo locale, ma in produzione significa che i job vengono eseguiti in modo sincrono dentro la richiesta HTTP. Per questo genere di valutazioni, Doctor riconduce l’applicazione a due modalità: local o production. I nomi di ambiente standard di Laravel — local, production, staging — vengono riconosciuti automaticamente. Se usi nomi diversi, raggruppali in modalità dal file di configurazione.

Diagnostic standard

Doctor include già di serie una suite di diagnostic che comprende:
  • Ambiente — esistenza del .env, APP_KEY, versione PHP, estensioni richieste, timezone
  • Composer — stato di installazione delle dipendenze, ottimizzazione dell’autoload, auto-fix del composer.lock
  • Configurazione — caricabilità/cachabilità dei file di config, valori richiesti dai driver attivi
  • Database — raggiungibilità della connessione, esistenza dei file SQLite, applicazione automatica delle migrazioni in sospeso
  • Cache / coda / scheduler / sessione — raggiungibilità dei driver configurati, rilevamento della coda sync fuori produzione
  • Storage — raggiungibilità del disk di default, permessi di scrittura sulle directory necessarie, esistenza di storage:link
  • Sicurezza — coerenza tra debug mode e ambiente, presenza di .env nel .gitignore, audit delle dipendenze Composer

Creare diagnostic personalizzati

Per creare una classe diagnostic personalizzata basta estendere Laravel\Doctor\Diagnostic e implementare check(). Puoi anche generare lo scaffold con il comando Artisan make:diagnostic.
Ecco un esempio di diagnostic che controlla l’APP_KEY e la genera automaticamente se non impostata.
Se la correzione ha senso solo con delle opzioni, puoi dichiararle con fixOptions(). La CLI le mostra come lista di scelta e il valore selezionato viene passato a fix().
In fondo alla lista di scelta viene sempre aggiunta l’opzione per rinunciare alla correzione (default: Skip — leave unfixed). Se ha più senso esprimerla come “mantieni la scelta corrente”, puoi indicare l’etichetta decline.

Helper per i diagnostic

Molte applicazioni e pacchetti scrivono spesso lo stesso tipo di controlli, quindi Doctor offre nel namespace Laravel\Doctor\Support helper per i pattern più frequenti. L’helper Configured legge i valori di configurazione in modo difensivo. Poiché i diagnostic devono poter analizzare anche applicazioni con configurazione rotta senza lanciare eccezioni, questi metodi non sollevano eccezioni con tipi imprevisti — a differenza degli accessor tipizzati del config repository.
L’helper ActiveDrivers risolve i driver “wrapper” (come il default log channel stack o il mailer failover) ai canali o mailer effettivamente utilizzati.
L’helper Details formatta le evidenze da allegare con withDetails(). Details::bullets() trasforma una lista di stringhe in bullet, Details::failures() gestisce messaggi di fallimento con chiave e Details::processOutput() sceglie lo stream di output più utile da un processo terminato.
Anche i pacchetti possono registrare diagnostic dai loro service provider usando la stessa API.
Nel report viene indicato il pacchetto che ha fornito il diagnostic.

Esecuzione programmatica

Puoi anche chiamare Doctor::run() senza passare per il comando Artisan.
Per applicare correzioni anche nell’esecuzione programmatica, imposta fixUsing. La callback riceve l’esito di un diagnostic fallito che offre una correzione e può restituire false per saltare, true per applicare la correzione standard, oppure il valore di un’opzione di correzione per applicare la scelta corrispondente. Quando la correzione viene applicata, Doctor rilancia il diagnostic per riflettere l’esito nel report.

Formati di output e supporto agli agenti AI

Per default Doctor produce output CLI leggibili, ma puoi scegliere anche JSON o il formato annotazioni per GitHub Actions.
Se, tramite Laravel Agent Detector, Doctor rileva che è in esecuzione dentro un agente di coding AI come Claude Code o Cursor, adotta come default un formato ottimizzato per gli agenti, seguendo le stesse convenzioni di Laravel PAO.
I problemi con fixable: true si risolvono rilanciando --fix. Per provare questo formato fuori da un agente, esegui AI_AGENT=test php artisan doctor.

Conclusioni

laravel/doctor è uno strumento che, con il solo comando php artisan doctor, ti permette di individuare rapidamente problemi di configurazione, ambiente e infrastruttura dell’applicazione. Ha un’ottima affinità con gli agenti di coding AI e restituisce un output con le stesse convenzioni di Laravel PAO, facile da interpretare per un agente, quindi vale la pena valutarne l’integrazione in workflow CI/CD e in flussi di auto-remediation gestiti da agenti.

Repository laravel/doctor

Codice sorgente e novità più recenti.
Ultima modifica il 2 agosto 2026