> ## 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 — l'outil de diagnostic d'application

> Présentation de laravel/doctor, le package officiel qui diagnostique les problèmes classiques de configuration, d'environnement et d'infrastructure et applique automatiquement les correctifs sûrs. Lancement via la commande php artisan doctor. Publié le 28 juillet 2026.

## Introduction

[laravel/doctor](https://github.com/laravel/doctor) est le package officiel qui diagnostique les problèmes courants de configuration, d'environnement et d'infrastructure dans une application Laravel. La version 0.1.0 est sortie le 28 juillet 2026.

Chaque diagnostic est une vérification unitaire. Par exemple, on peut vérifier « Laravel peut-il écrire dans le répertoire storage ? » et obtenir l'un des statuts prévus. Lorsqu'un correctif sûr et déterministe est possible, il est proposé automatiquement ; sinon (par exemple un échec de build d'assets), une marche à suivre (remediation) est présentée.

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

## Exécution

Une fois le package installé, la commande Artisan `doctor` est disponible.

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

Si un problème corrigeable est détecté, Doctor le signale puis demande confirmation avant d'appliquer le correctif.

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

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

Pour appliquer les correctifs sans demande de confirmation, utilisez l'option `--fix`.

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

Les correctifs standard couvrent des opérations locales déterministes : création du fichier `.env`, génération de `APP_KEY`, désactivation du mode debug en production, ajout de `.env` à `.gitignore`, création du `storage:link`, ajustement des permissions d'écriture dans `storage`, etc.

<Info>
  Les correctifs ne sont disponibles que dans les formats de sortie CLI et « agent ». Pour les formats JSON et GitHub, la commande refuse `--fix` afin de garantir que le rapport machine-lisible n'entraîne aucune modification de l'application.
</Info>

`--bail` interrompt l'exécution au premier diagnostic en échec ou en erreur.

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

## Statuts des diagnostics

Chaque diagnostic renvoie l'un des statuts suivants.

| Statut   | Signification                                               | Impact sur le code de sortie    |
| -------- | ----------------------------------------------------------- | ------------------------------- |
| `pass`   | Vérification réussie, tout va bien                          | Aucun                           |
| `notice` | Information utile pour le développeur                       | Aucun                           |
| `warn`   | Problème potentiel qui peut ne pas nécessiter d'action      | Seulement avec `--fail-on=warn` |
| `fail`   | Problème détecté à corriger                                 | Oui                             |
| `skip`   | Non applicable à l'environnement courant                    | Aucun                           |
| `error`  | Une exception est survenue durant l'exécution du diagnostic | Oui                             |

Par défaut, un `fail` ou un `error` fait sortir la commande en échec. Avec `--fail-on=warn`, les avertissements font aussi échouer ; avec `--fail-on=never`, la commande se contente de rapporter les problèmes.

## Sélection des diagnostics

Vous pouvez sélectionner ou exclure des diagnostics par nom de classe, par groupe, par package ou par joker de package.

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

php artisan doctor --only=StorageIsWritable

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

En publiant le fichier de configuration, vous pouvez rendre cette sélection permanente.

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

## Modes d'environnement

Une file `sync` est raisonnable en développement local, mais en production cela signifie que les jobs sont exécutés de manière synchrone dans la requête HTTP. Pour tenir compte de ce type de nuance, Doctor résout l'application dans l'un des deux modes suivants : `local` ou `production`.

| Mode         | État attendu                                                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `local`      | En développement. Mode debug, file `sync`, fichiers bootstrap non mis en cache sont normaux.                                                   |
| `production` | Traitement de trafic réel. Le mode debug est un risque de sécurité, les files doivent être asynchrones et les fichiers bootstrap mis en cache. |

Les noms d'environnement standard de Laravel (`local`, `production`, `staging`) sont détectés automatiquement. Pour d'autres noms, groupez-les par mode dans le fichier de configuration.

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

## Diagnostics fournis en standard

Doctor est livré avec une suite de diagnostics couvrant notamment :

* **Environnement** — présence du `.env`, `APP_KEY`, version de PHP, extensions requises, timezone.
* **Composer** — installation des dépendances, optimisation de l'autoloader, correction automatique du `composer.lock`.
* **Configuration** — lecture et mise en cache du fichier de configuration, valeurs requises par les drivers activés.
* **Base de données** — accessibilité des connexions, existence du fichier SQLite, exécution automatique des migrations en attente.
* **Cache, files, scheduler, sessions** — accessibilité des drivers configurés, détection d'une file `sync` en dehors du mode local.
* **Storage** — accessibilité du disque par défaut, permissions d'écriture des répertoires nécessaires, présence du `storage:link`.
* **Sécurité** — cohérence entre le mode debug et l'environnement, présence du `.env` dans `.gitignore`, audit des dépendances Composer.

## Créer un diagnostic personnalisé

Il suffit d'étendre `Laravel\Doctor\Diagnostic` et d'implémenter la méthode `check()`. La commande Artisan `make:diagnostic` permet aussi de générer le squelette.

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

Voici un exemple qui vérifie la configuration de `APP_KEY` et la génère si elle est absente.

```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');
    }
}
```

Lorsqu'un correctif comporte plusieurs options, déclarez-les via `fixOptions()`. Le CLI affiche alors une liste de choix et la valeur sélectionnée est transmise à `fix()`.

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

En fin de liste, un choix pour renoncer au correctif est toujours ajouté (par défaut `Skip — leave unfixed`). Si un libellé « conserver l'état actuel » est plus explicite, précisez-le via `decline`.

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

### Helpers de diagnostic

Comme de nombreuses applications ou packages écrivent le même type de vérifications, Doctor fournit des helpers pour les motifs les plus courants dans l'espace de noms `Laravel\Doctor\Support`.

Le helper `Configured` lit défensivement une valeur de configuration. Un diagnostic doit pouvoir inspecter une application dont la configuration est cassée sans lever d'exception avant d'avoir pu rendre son rapport ; contrairement aux accesseurs typés du dépôt de configuration, ces méthodes ne lèvent pas d'exception face à un type inattendu.

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

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

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

Le helper `ActiveDrivers` résout les drivers « wrappers » (comme un canal de log par défaut `stack` ou un mailer `failover`) vers les canaux ou mailers concrètement utilisés.

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

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

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

Le helper `Details` met en forme les preuves à joindre via `withDetails()`. `Details::bullets()` transforme une liste de chaînes en puces, `Details::failures()` en messages d'échec clefés, et `Details::processOutput()` sélectionne le flux de sortie le plus pertinent d'un processus terminé.

```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.']);
```

Un package peut enregistrer un diagnostic depuis son service provider en utilisant la même API.

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

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

Le rapport indique alors le package d'origine du 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.
```

## Exécution programmatique

Vous pouvez appeler `Doctor::run()` sans passer par la commande Artisan.

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

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

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

Pour appliquer les correctifs en mode programmatique, configurez `fixUsing`. Le callback reçoit le diagnostic en échec qui propose un correctif ; renvoyer `false` saute le correctif, `true` applique le correctif standard, ou renvoyer une valeur d'option applique ce choix spécifique. Une fois un correctif appliqué, Doctor relance le diagnostic pour refléter l'état dans le rapport.

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

$report->fixes();
```

## Formats de sortie et compatibilité avec les agents IA

Par défaut, Doctor produit une sortie CLI lisible, mais vous pouvez choisir un format JSON ou des annotations GitHub Actions.

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

php artisan doctor --format=github
```

Grâce à [Laravel Agent Detector](https://github.com/laravel/agent-detector), lorsque Doctor détecte qu'il s'exécute dans un agent de code IA (Claude Code, Cursor…), il bascule par défaut sur un format optimisé pour les agents, calqué sur celui de [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}]}
```

Les problèmes marqués `fixable: true` peuvent être résolus en relançant avec `--fix`. Pour tester ce format hors d'un agent, exécutez `AI_AGENT=test php artisan doctor`.

## Conclusion

`laravel/doctor` permet, via une simple commande `php artisan doctor`, d'identifier rapidement les problèmes de configuration, d'environnement et d'infrastructure d'une application. Sa bonne intégration avec les agents de code IA — via une sortie conforme aux conventions de Laravel PAO — en fait aussi un candidat sérieux pour les pipelines CI/CD et les workflows d'auto-remédiation pilotés par un agent.

<Card title="Dépôt laravel/doctor" icon="github" href="https://github.com/laravel/doctor">
  Le code source et les dernières informations.
</Card>


## Related topics

- [Outils](/fr/packages/laravel-copilot-sdk/tools.md)
- [Laravel Telescope](/fr/telescope.md)
- [Hooks de session](/fr/packages/laravel-copilot-sdk/hooks.md)
- [Cycle de vie d'une requête](/fr/lifecycle.md)
- [Le nouvel écosystème d'analyse de code Laravel — surveyor / ranger / roster](/fr/blog/laravel-ecosystem-analysis.md)