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 Artisandoctor.
--fix.
.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.--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.Modalità ambiente
La codasync è 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
syncfuori 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
.envnel.gitignore, audit delle dipendenze Composer
Creare diagnostic personalizzati
Per creare una classe diagnostic personalizzata basta estendereLaravel\Doctor\Diagnostic e implementare check(). Puoi anche generare lo scaffold con il comando Artisan make:diagnostic.
APP_KEY e la genera automaticamente se non impostata.
fixOptions(). La CLI le mostra come lista di scelta e il valore selezionato viene passato a fix().
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 namespaceLaravel\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.
ActiveDrivers risolve i driver “wrapper” (come il default log channel stack o il mailer failover) ai canali o mailer effettivamente utilizzati.
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.
Esecuzione programmatica
Puoi anche chiamareDoctor::run() senza passare per il comando Artisan.
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.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.