Laravel Doctor: Diagnostica la tua app con un comando Artisan

Laravel Doctor: Diagnostica la tua app con un comando Artisan

Laravel Doctor è stato annunciato al Laracon US 2026 a Boston, aggiungendo un comando artisan doctor che esegue controlli di salute sulla tua applicazione. Dal comunicato:

Artisan doctor esegue una serie di controlli di salute sulla tua applicazione Laravel: la tua APP_KEY è impostata, la tua versione PHP corrisponde a quella prevista da Composer, le estensioni richieste sono installate e la configurazione dell'ambiente è completa? Dove può correggere un problema automaticamente, lo fa. Dove non può, ti dice esattamente cosa non va.

Diagnosticare un'installazione Laravel rotta di solito significava controllare una lista mentale: c'è .env, la chiave è generata, storage/ è scrivibile, la connessione della coda non è sync in produzione. Doctor trasforma quella lista in codice e offre ai pacchetti un posto dove aggiungere le proprie voci.

Come funziona

Ogni diagnostica è una singola classe che ispeziona una cosa e restituisce uno di sei stati: pass, notice, warn, fail, skip o error. Di default, il comando termina con uno stato diverso da zero se qualcosa fallisce o se si verificano errori. Se vuoi che anche i warning facciano fallire una build, passa --fail-on=warn. Se vuoi solo il report e mai un codice di uscita fallito, usa --fail-on=never.

La suite inclusa copre:

• Ambiente: presenza di .env, APP_KEY, versione PHP rispetto al vincolo di composer.json, estensioni richieste e raccomandate, e fuso orario.
• Composer: dipendenze installate, possibilità di generare i file autoload ottimizzati e problemi riparabili di composer.lock.
• Configurazione: caricamento e cache dei file di configurazione, valori richiesti dai driver attivi impostati e stato della bootstrap cache.
• Database: la connessione predefinita è raggiungibile, il file SQLite esiste quando necessario e ci sono migrations in sospeso.
• Cache, code, scheduler e sessione: i driver configurati sono raggiungibili, le connessioni Redis vengono controllate e le attività pianificate vengono mostrate come un notice.
• Storage: il disco predefinito è raggiungibile, le directory richieste sono scrivibili e il symlink storage:link esiste.
• Sicurezza: la modalità debug corrisponde all'ambiente, .env è ignorato da git e le dipendenze vengono verificate.

Alcuni di questi non possono essere giudicati in isolamento, quindi Doctor risolve la tua app in una delle due modalità, local o production, e la modalità decide se qualcosa costituisce un problema o meno. Una connessione alla coda sync passa in locale e ti avverte in produzione. Le bootstrap cache mancanti avvertono in produzione ma passano in locale, mentre le cache presenti passano in produzione e generano un notice in locale, poiché una cache obsoleta è una causa comune per cui le modifiche recenti non vengono mostrate mentre lavori. Laravel Doctor conosce local, production e staging di default, e tutto ciò che non riconosce viene valutato secondo le aspettative di produzione.

Per iniziare

Installalo come dipendenza di sviluppo:

composer require laravel/doctor --dev

Poi eseguilo:

php artisan doctor

Quando una diagnostica che fallisce può essere riparata, Doctor segnala il problema e ti chiede conferma prima di fare qualsiasi cosa:

Storage is writable: The application cannot write to every required storage directory.

 Make the storage directories writable? (yes/no) [yes]

php artisan doctor --fix salta la richiesta di conferma. Può creare un .env mancante, generare APP_KEY, disattivare la modalità debug in produzione, aggiungere .env a .gitignore, creare il link di storage pubblico e riparare i permessi delle directory di storage. Altre riparazioni richiedono che un essere umano scelga tra opzioni, ad esempio a quale cache store passare quando quello predefinito non è raggiungibile. Queste vengono mostrate come una lista selezionabile quando esegui il comando in modo interattivo e in --fix diventano normali errori.

Le diagnostiche possono essere filtrate per nome della classe, gruppo, pacchetto o wildcard del pacchetto:

php artisan doctor --only=security

php artisan doctor --except=laravel/*

Se vuoi che vengano sempre applicati gli stessi selettori, pubblica il file di configurazione con php artisan vendor:publish --tag=doctor-config e impostali lì.

Diagnostiche personalizzate

I pacchetti possono registrare diagnostiche dal loro service provider tramite la facade Doctor, nello stesso modo in cui farebbe un'applicazione:

use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;

public function boot(): void
{
    Doctor::diagnostic(HorizonIsRunning::class);
}

I report mostrano da quale pacchetto Composer proviene ogni diagnostica:

[fail] Storage is writable (laravel/doctor): The application cannot write to every required storage directory.
[pass] SQLite database exists (acme/application): The SQLite database file exists.
[warn] Horizon is running (laravel/horizon): Horizon is not currently running.

Eseguire php artisan make:diagnostic HorizonIsRunning genera uno scaffold in app/Doctor/Diagnostics. Estende Laravel\Doctor\Diagnostic e implementa un metodo check() che restituisce un DiagnosticResult. La formulazione dei messaggi risiede separatamente in un metodo messages(), in cui ogni Message::make() contiene un riepilogo, il testo di rimedio, i link alla documentazione e il prompt di conferma mostrato prima di eseguire una correzione.

Se il tuo check può riparare ciò che trova, implementa Laravel\Doctor\Contracts\Fixable e contrassegna i fallimenti specifici con ->fixable(). Questo metodo accetta anche un EnvironmentMode, così una riparazione può essere limitata a una macchina di sviluppo.

Output per CI e agenti AI

L'output CLI è quello predefinito, ma --format=json produce un report leggibile da una macchina e --format=github genera annotazioni per GitHub Actions. Doctor rifiuta --fix con entrambi, così un report destinato a una macchina non modifica mai l'applicazione.

C'è un quarto formato pensato per agenti di codifica, e Doctor ci passa automaticamente quando Laravel Agent Detector rileva che sta girando all'interno di qualcosa come Claude Code o Cursor. Segue la convenzione Laravel PAO: una riga di JSON, i conteggi in cima e solo i risultati su cui puoi intervenire vengono elencati.

{"tool":"doctor","result":"failed","diagnostics":27,"failed":1,"warnings":1,"notices":0,"passed":19,"skipped":6,"issues":[{"name":".env file exists","status":"fail","summary":"The application does not have an environment file.","fix":"Run `cp .env.example .env`, then review the copied values.","fixable":true}]}

Il che è la premessa per il resto dell'annuncio:

I pacchetti possono registrare i propri controlli diagnostici, quindi un pacchetto con requisiti di configurazione specifici può integrarsi direttamente con artisan doctor ed esporre i propri controlli di salute accanto a quelli del framework. È anche un naturale passo finale per gli agenti AI di codifica: dopo aver apportato modifiche, un agente può eseguire artisan doctor come controllo finale di sanità prima di considerare completata un'attività.

Tutto ciò che viene contrassegnato come fixable può essere risolto rieseguendo il comando con --fix, che applica le correzioni, riesegue le diagnostiche e aggiunge gli esiti al payload. Tutto ciò che viene restituito con una mappa options richiede una scelta che --fix non prende da solo; in questo caso l'agente deve seguire il testo di rimedio o passare la rosa di opzioni a un essere umano. Per vedere il formato senza un agente, esegui AI_AGENT=test php artisan doctor.

Doctor può essere eseguito anche senza il comando Artisan. Doctor::run() restituisce un DiagnosticReport, e only(), except(), bail() e fixUsing() limitano l'esecuzione a livello di codice.

Scopri di più

Laravel Doctor richiede PHP 8.3 e Laravel 12 o 13, ed è concesso in licenza MIT. La documentazione completa, inclusi gli helper diagnostici in Laravel\Doctor\Support e la guida completa per scrivere i tuoi controlli, si trova nel repository GitHub di Laravel Doctor.