Skip to main content

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-Befehl doctor registriert.
Findet Doctor behebbare Probleme, meldet es diese und fragt vor dem Fix nach.
Möchten Sie Fixes ohne Rückfrage anwenden, verwenden Sie die Option --fix.
Die Standard-Fixes decken deterministische lokale Reparaturen ab, darunter das Erstellen von .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.
Mit --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.
Durch Veröffentlichen der Konfigurationsdatei können Sie auch dauerhafte Auswahleinstellungen definieren.

Umgebungsmodi

Die sync-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 .env in .gitignore, Audit der Composer-Abhängigkeiten

Eigene Diagnostics erstellen

Um eine eigene Diagnostic-Klasse zu erstellen, genügt es, von Laravel\Doctor\Diagnostic zu erben und die Methode check() zu implementieren. Ein Grundgerüst kann per Artisan-Befehl make:diagnostic generiert werden.
Nachfolgend ein Beispiel, das die APP_KEY-Einstellung prüft und – falls nicht gesetzt – automatisch generiert.
Wenn ein Fix mit Auswahlmöglichkeiten sinnvoll ist, können Sie die Optionen mit fixOptions() deklarieren. Die CLI zeigt sie als Auswahlliste an, und der gewählte Wert wird an fix() übergeben.
Am Ende der Auswahlliste wird immer eine Option angehängt, den Fix zu überspringen (Standard: 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 Namespace Laravel\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.
Der 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.
Der 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.
Auch Pakete können über dieselbe API Diagnostics aus ihrem Service Provider heraus registrieren.
Im Report wird angezeigt, aus welchem Paket die Diagnostic stammt.

Programmatische Ausführung

Sie können Doctor::run() auch direkt aufrufen, ohne den Artisan-Befehl zu verwenden.
Wenn Sie auch aus dem Programm heraus Fixes anwenden möchten, setzen Sie 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.
Wird über den Laravel Agent Detector die Ausführung innerhalb eines KI-Coding-Agents wie Claude Code oder Cursor erkannt, wird standardmäßig ein agent-optimiertes Format nach denselben Konventionen wie Laravel PAO verwendet.
Probleme mit 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.
Zuletzt geändert am 2. August 2026