Einführung
laravel/doctor ist ein offizielles Paket, das gängige Probleme in Konfiguration, Umgebung und Infrastruktur einer Laravel-Anwendung diagnostiziert. Die Version v0.1.0 wurde am 28. Juli 2026 veröffentlicht. Jede Diagnostic ist eine einzelne Prüfung. Sie prüft beispielsweise „Kann Laravel in das storage-Verzeichnis schreiben?” und meldet einen von mehreren möglichen Status. Wenn eine Behebung sicher und deterministisch möglich ist, wird auch ein automatischer Fix angeboten; für nicht automatisch behebbare Probleme wie fehlgeschlagene Asset-Builds werden Handlungsanleitungen (Remediation) angezeigt.Ausführung
Nach der Installation wird der Artisan-Befehldoctor registriert.
--fix.
.env, das Generieren von APP_KEY, das Deaktivieren des Debug-Modus in Produktion, das Hinzufügen von .env zu .gitignore, das Anlegen von storage:link sowie das Wiederherstellen der Schreibrechte für storage-Verzeichnisse.
Die Fix-Funktion ist nur bei den Ausgabeformaten CLI und Agent verfügbar. Bei JSON- und GitHub-Report-Formaten wird
--fix verweigert, damit maschinenlesbare Reports die Anwendung nicht verändern.--bail wird die Ausführung bei der ersten fehlgeschlagenen oder fehlerhaften Diagnostic gestoppt.
Diagnostic-Status
Jede Diagnostic gibt einen der folgenden Status zurück.
Standardmäßig führt
fail oder error zu einem Exit mit Fehlerstatus. Mit --fail-on=warn können auch Warnungen zum Fehlschlag führen, mit --fail-on=never werden Probleme lediglich gemeldet.
Auswahl von Diagnostics
Diagnostics lassen sich nach Klassenname, Gruppe, Paket oder Paket-Wildcard ein- und ausschließen.Umgebungsmodi
Diesync-Queue ist ein vertretbarer Default in der lokalen Entwicklung, bedeutet in der Produktion jedoch, dass Queue-Jobs synchron innerhalb der Web-Requests ausgeführt werden. Aufgrund solcher Bewertungen löst Doctor die Anwendung in einen von zwei Modi auf: local oder production.
Die Standard-Laravel-Umgebungsnamen
local, production und staging werden automatisch erkannt. Für andere Namen können Sie die Zuordnung zu den Modi in der Konfigurationsdatei vornehmen.
Standard-Diagnostics
Doctor liefert eine Suite von Standard-Diagnostics mit, darunter:- Umgebung — Existenz von
.env,APP_KEY, PHP-Version, benötigte Extensions, Zeitzone - Composer — Installationsstand der Abhängigkeiten, Autoloader-Optimierung, automatische Reparatur von
composer.lock - Konfiguration — Ladbarkeit und Cachbarkeit der Konfigurationsdateien, von aktiven Treibern benötigte Konfigurationswerte
- Datenbank — Erreichbarkeit der Verbindungen, Existenz von SQLite-Dateien, automatisches Anwenden ausstehender Migrationen
- Cache, Queue, Scheduler, Session — Erreichbarkeit der konfigurierten Treiber, Erkennung von
sync-Queues außerhalb der Produktion - Storage — Erreichbarkeit des Standard-Disks, Schreibrechte für erforderliche Verzeichnisse, Vorhandensein von
storage:link - Sicherheit — Konsistenz von Debug-Modus und Umgebung, Registrierung von
.envin.gitignore, Audit der Composer-Abhängigkeiten
Eigene Diagnostics erstellen
Um eine eigene Diagnostic-Klasse zu erstellen, genügt es, vonLaravel\Doctor\Diagnostic zu erben und die Methode check() zu implementieren. Ein Grundgerüst kann per Artisan-Befehl make:diagnostic generiert werden.
APP_KEY-Einstellung prüft und – falls nicht gesetzt – automatisch generiert.
fixOptions() deklarieren. Die CLI zeigt sie als Auswahlliste an, und der gewählte Wert wird an fix() übergeben.
Skip — leave unfixed). Wenn ein Text besser passt, der das Beibehalten der aktuellen Auswahl ausdrückt, können Sie ein decline-Label angeben.
Diagnostic-Helper
Da viele Anwendungen und Pakete ähnliche Arten von Prüfungen wiederholt schreiben müssen, bietet Doctor unter dem NamespaceLaravel\Doctor\Support Helper für häufige Muster.
Der Configured-Helper liest Konfigurationswerte defensiv aus. Da eine Diagnostic auch eine Anwendung mit beschädigter Konfiguration untersuchen und ordentlich melden können muss, werfen diese Methoden – anders als die typisierten Accessoren des Config-Repository – auch bei unerwarteten Typen keine Exceptions.
ActiveDrivers-Helper löst Wrapper-Treiber – etwa wenn der Standard-Log-Channel stack oder der Mailer failover ist – zu den konkret genutzten Channels bzw. Mailern auf.
Details-Helper formatiert Beweisinformationen, die an withDetails() angehängt werden. Details::bullets() erzeugt aus einer Liste von Strings eine Aufzählung, Details::failures() verarbeitet gekeyte Fehlermeldungen und Details::processOutput() wählt aus einem beendeten Prozess den nützlichsten Output-Stream aus.
Programmatische Ausführung
Sie könnenDoctor::run() auch direkt aufrufen, ohne den Artisan-Befehl zu verwenden.
fixUsing. Der Callback erhält die fehlgeschlagene Diagnostic, die einen Fix anbietet, und gibt false für Überspringen, true für einen normalen Fix oder einen Fix-Options-Wert zurück, um mit dieser Auswahl zu fixen. Nach dem Anwenden eines Fixes führt Doctor die Diagnostic erneut aus, damit dies im Report reflektiert wird.
Ausgabeformate und KI-Agent-Unterstützung
Standardmäßig erzeugt Doctor eine gut lesbare CLI-Ausgabe, es stehen aber auch JSON und GitHub-Actions-Annotations zur Auswahl.fixable: true lassen sich durch einen erneuten Lauf mit --fix beheben. Um dieses Format außerhalb eines Agents auszuprobieren, führen Sie AI_AGENT=test php artisan doctor aus.
Fazit
laravel/doctor ist ein Werkzeug, mit dem Sie durch einen einzigen php artisan doctor-Aufruf schnell Probleme in Konfiguration, Umgebung und Infrastruktur Ihrer Anwendung aufspüren. Da es sich hervorragend mit KI-Coding-Agenten kombinieren lässt und die für Agents leicht interpretierbare Ausgabe denselben Konventionen wie Laravel PAO folgt, lohnt sich auch die Einbindung in CI/CD- oder KI-gestützte Auto-Fix-Workflows.
laravel/doctor Repository
Quellcode und neueste Informationen hier.