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

# Laravel Doctor — strumento di diagnostica per l'applicazione

> Introduzione a laravel/doctor. Pacchetto ufficiale Laravel che diagnostica i problemi comuni di configurazione, ambiente e infrastruttura e corregge automaticamente quelli sicuri. Si esegue con il comando php artisan doctor. Rilascio del 28 luglio 2026.

## Introduzione

[laravel/doctor](https://github.com/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).

```bash theme={null}
composer require laravel/doctor --dev
```

## Come eseguirlo

Dopo l'installazione viene registrato il comando Artisan `doctor`.

```bash theme={null}
php artisan doctor
```

Quando trova problemi correggibili, Doctor segnala il problema e chiede conferma per la correzione.

```text theme={null}
Storage is writable: The application cannot write to every required storage directory.

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

Per applicare la correzione senza conferma usa l'opzione `--fix`.

```bash theme={null}
php artisan doctor --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.

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

Con `--bail` l'esecuzione si ferma al primo diagnostic con esito failure o error.

```bash theme={null}
php artisan doctor --bail
```

## Stato dei diagnostic

Ogni diagnostic restituisce uno dei seguenti stati.

| Stato    | Significato                                        | Influisce sul codice di uscita |
| -------- | -------------------------------------------------- | ------------------------------ |
| `pass`   | Controllo superato, nessun problema                | No                             |
| `notice` | Informazione utile da comunicare allo sviluppatore | No                             |
| `warn`   | Potenziale problema che può non richiedere azione  | Solo con `--fail-on=warn`      |
| `fail`   | Rilevato problema da risolvere                     | Sì                             |
| `error`  | Eccezione durante l'esecuzione del diagnostic      | Sì                             |

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.

```bash theme={null}
php artisan doctor --only=storage

php artisan doctor --only=StorageIsWritable

php artisan doctor --except=laravel/*
```

Pubblicando il file di configurazione puoi impostare selezioni persistenti.

```bash theme={null}
php artisan vendor:publish --tag=doctor-config
```

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

| Modalità     | Stato atteso                                                                                                                           |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `local`      | In sviluppo. Debug mode, coda `sync`, file di bootstrap non in cache sono normali                                                      |
| `production` | Elabora traffico reale. Debug mode è un rischio di sicurezza, la coda dev'essere asincrona, i file di bootstrap devono essere in cache |

I nomi di ambiente standard di Laravel — `local`, `production`, `staging` — vengono riconosciuti automaticamente. Se usi nomi diversi, raggruppali in modalità dal file di configurazione.

```php theme={null}
'environments' => [
    'local' => ['local', 'dev'],
    'production' => ['production', 'staging', 'qa'],
],
```

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

```bash theme={null}
php artisan make:diagnostic HorizonIsRunning --fixable
```

Ecco un esempio di diagnostic che controlla l'`APP_KEY` e la genera automaticamente se non impostata.

```php theme={null}
namespace App\Doctor\Diagnostics;

use Illuminate\Support\Facades\Artisan;
use Laravel\Doctor\Contracts\Fixable;
use Laravel\Doctor\Diagnostic;
use Laravel\Doctor\EnvironmentMode;
use Laravel\Doctor\Results\DiagnosticResult;
use Laravel\Doctor\Results\FixResult;

class ApplicationKeyIsSet extends Diagnostic implements Fixable
{
    public string $name = 'App key is set';

    public string $group = 'environment';

    protected function messages(): array
    {
        return [
            'configured' => 'The application key is configured.',
            'missing' => 'The application key is not configured.',
            'generated' => 'The application key was generated.',
        ];
    }

    public function check(): DiagnosticResult
    {
        $key = config('app.key');

        if (is_string($key) && trim($key) !== '') {
            return $this->pass('configured');
        }

        return $this->fail('missing')->fixable(EnvironmentMode::Local);
    }

    public function fix(DiagnosticResult $result): FixResult
    {
        Artisan::call('key:generate', ['--force' => true]);

        return $this->fixed('generated');
    }
}
```

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()`.

```php theme={null}
return $this->fail('unreachable')
    ->fixable(EnvironmentMode::Local)
    ->fixOptions(['file' => 'File', 'redis' => 'Redis']);
```

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

```php theme={null}
->fixOptions(['file' => 'File'], decline: 'Keep Redis (repair it manually)');
```

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

```php theme={null}
use Laravel\Doctor\Support\Configured;

$connection = Configured::string('queue.default', 'database');

$missing = Configured::missing([
    'services.stripe.key',
    'services.stripe.secret',
]);
```

L'helper `ActiveDrivers` risolve i driver "wrapper" (come il default log channel `stack` o il mailer `failover`) ai canali o mailer effettivamente utilizzati.

```php theme={null}
use Laravel\Doctor\Support\ActiveDrivers;

$channels = ActiveDrivers::logChannels(Configured::string('logging.default', 'stack'));

$mailers = ActiveDrivers::mailers(Configured::string('mail.default', 'log'));
```

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.

```php theme={null}
use Laravel\Doctor\Support\Details;

Details::bullets(['services.stripe.key', 'services.stripe.secret']);

Details::failures(['media' => 'The disk root is not writable.']);
```

Anche i pacchetti possono registrare diagnostic dai loro service provider usando la stessa API.

```php theme={null}
use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;

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

Nel report viene indicato il pacchetto che ha fornito il diagnostic.

```text theme={null}
[fail] Storage is writable (laravel/doctor): The application cannot write to every required storage directory.
[warn] Horizon is running (laravel/horizon): Horizon is not currently running.
```

## Esecuzione programmatica

Puoi anche chiamare `Doctor::run()` senza passare per il comando Artisan.

```php theme={null}
use Laravel\Doctor\Facades\Doctor;

$report = Doctor::only('security')
    ->except(SomeDiagnostic::class)
    ->run();

if ($report->hasFailures()) {
    // ...
}
```

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.

```php theme={null}
$report = Doctor::fixUsing(
    fn ($outcome) => $outcome->fixRequiresOption() ? false : true,
)->run();

$report->fixes();
```

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

```bash theme={null}
php artisan doctor --format=json

php artisan doctor --format=github
```

Se, tramite [Laravel Agent Detector](https://github.com/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](https://github.com/laravel/pao).

```json theme={null}
{"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}]}
```

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.

<Card title="Repository laravel/doctor" icon="github" href="https://github.com/laravel/doctor">
  Codice sorgente e novità più recenti.
</Card>


## Related topics

- [Configurazione](/it/configuration.md)
- [Laravel Telescope](/it/telescope.md)
- [Struttura delle directory](/it/directory-structure.md)
- [Tutorial per bot - Laravel Bluesky](/it/packages/laravel-bluesky/bot-tutorial.md)
- [Laravel Horizon](/it/horizon.md)