L’idée est simple, mais franchement bienvenue: transformer la fameuse liste mentale du développeur — « le .env est-il présent? », « la clé est-elle générée? », « les extensions PHP sont-elles installées? » — en diagnostics exécutables. Pour les équipes PHP, c’est surtout une nouvelle manière de repérer les installations fragiles avant qu’elles ne deviennent le ticket urgent du vendredi soir.
Et si Laravel arrêtait de nous faire jouer au détective?
Sous le capot, php artisan doctor vérifie notamment la présence de APP_KEY, la compatibilité de la version de PHP avec les attentes de Composer, les extensions requises et la complétude de la configuration de l’environnement. Le paquet peut également examiner des éléments comme les répertoires de stockage, les caches de démarrage ou encore la connexion de queue.
La sortie du diagnostic repose sur six statuts: pass, notice, warn, fail, skip et error. Autrement dit, on ne reçoit pas seulement un vague « quelque chose ne va pas » façon legacy applicatif. La commande indique la nature du problème et retourne, par défaut, un code d’échec si un diagnostic aboutit à fail ou error.
C’est là que le sujet devient intéressant pour nos pipelines: avec --fail-on=warn, les avertissements peuvent eux aussi faire échouer le build. À l’inverse, --fail-on=never permet de produire uniquement un rapport, sans provoquer d’échec. On peut donc l’utiliser comme garde-fou strict dans une CI ou comme outil d’observation plus tranquille en local.
Local, production, staging: le même problème n’a pas toujours le même poids
Laravel Doctor ne semble pas traiter l’environnement comme un simple détail cosmétique. Il distingue les modes local, production et staging, et adapte l’interprétation de certains diagnostics.
Une connexion de queue synchrone peut ainsi être considérée comme acceptable en local, mais signalée en production. Même logique pour les caches de bootstrap: leur absence peut déclencher un avertissement en production, tout en étant tolérée sur une machine de développement. À l’inverse, un cache présent en local peut générer une notice — parce qu’un cache obsolète est un grand classique quand les modifications récentes refusent mystérieusement d’apparaître.
Et si l’environnement n’est pas reconnu? Doctor lui applique les attentes de la production. Une décision plutôt saine: mieux vaut un diagnostic prudent qu’un « tout va bien » optimiste qui attend tranquillement le déploiement pour se transformer en incident.
Peut-on réparer sans lancer une nouvelle refacto à l’aveugle?
La commande ne se limite pas au constat. Lorsqu’un problème peut être corrigé automatiquement, Doctor le signale et demande une confirmation avant d’agir. Avec php artisan doctor --fix, cette confirmation est ignorée.
Les réparations prévues peuvent notamment créer un .env manquant, générer APP_KEY, désactiver le mode debug en production, ajouter .env au .gitignore, créer le lien vers le stockage public ou corriger les permissions des répertoires de stockage. Pour les cas où plusieurs choix sont possibles — par exemple sélectionner un autre store de cache — l’outil affiche une liste en mode interactif. En mode --fix, ces situations redeviennent des échecs classiques, car Doctor ne choisit pas à la place de l’équipe.
Autre point qui mérite l’attention des mainteneurs de packages: les diagnostics sont extensibles. Ils peuvent être filtrés par classe, groupe, package ou wildcard de package, puis configurés durablement après publication du fichier dédié avec php artisan vendor:publish --tag=doctor-config.
Les packages peuvent aussi enregistrer leurs propres contrôles via leur service provider et la façade Doctor. La commande php artisan make:diagnostic HorizonIsRunning sert à générer un diagnostic dans app/Doctor/Diagnostics. Chaque contrôle renvoie un résultat, tandis que les messages — résumé, remédiation, documentation et demande de confirmation — restent séparés. Si le contrôle sait réparer le problème, il peut implémenter le contrat Fixable et limiter la correction à un mode d’environnement précis.
C’est probablement le vrai potentiel de Laravel Doctor: pas seulement une commande pratique pour vérifier une installation, mais un point d’entrée commun pour rendre nos applications et nos packages plus explicites sur leur état. On verra maintenant si l’écosystème s’en empare — et si nos vieux rituels de vérification manuelle finiront enfin dans le dossier legacy.