> ## 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 — Diagnosewerkzeug für Ihre Anwendung

> Einführung in laravel/doctor: Ein offizielles Laravel-Paket, das häufige Probleme bei Konfiguration, Umgebung und Infrastruktur diagnostiziert und, sofern sicher möglich, automatisch behebt. Ausführung über den Befehl php artisan doctor. Veröffentlicht am 28. Juli 2026.

## Einführung

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

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

## Ausführung

Nach der Installation wird der Artisan-Befehl `doctor` registriert.

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

Findet Doctor behebbare Probleme, meldet es diese und fragt vor dem Fix nach.

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

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

Möchten Sie Fixes ohne Rückfrage anwenden, verwenden Sie die Option `--fix`.

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

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

Mit `--bail` wird die Ausführung bei der ersten fehlgeschlagenen oder fehlerhaften Diagnostic gestoppt.

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

## Diagnostic-Status

Jede Diagnostic gibt einen der folgenden Status zurück.

| Status   | Bedeutung                                                    | Beeinflusst Exit-Code    |
| -------- | ------------------------------------------------------------ | ------------------------ |
| `pass`   | Prüfung erfolgreich, keine Probleme                          | Nein                     |
| `notice` | Information, die dem Entwickler mitteilenswert ist           | Nein                     |
| `warn`   | Potenzielles Problem, das nicht zwingend behoben werden muss | Nur bei `--fail-on=warn` |
| `fail`   | Ein zu behebendes Problem wurde erkannt                      | Ja                       |
| `skip`   | Trifft auf die aktuelle Umgebung nicht zu                    | Nein                     |
| `error`  | Beim Ausführen der Diagnostic ist eine Exception aufgetreten | Ja                       |

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.

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

php artisan doctor --only=StorageIsWritable

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

Durch Veröffentlichen der Konfigurationsdatei können Sie auch dauerhafte Auswahleinstellungen definieren.

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

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

| Modus        | Erwarteter Zustand                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `local`      | In Entwicklung. Debug-Modus, `sync`-Queue und ungecachete Bootstrap-Dateien sind normal                                         |
| `production` | Bedient echten Traffic. Debug-Modus ist ein Sicherheitsrisiko; Queues laufen asynchron; Bootstrap-Dateien sollten gecached sein |

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.

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

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

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

Nachfolgend ein Beispiel, das die `APP_KEY`-Einstellung prüft und – falls nicht gesetzt – automatisch generiert.

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

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.

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

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.

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

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

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

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

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

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.

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

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

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

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.

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

Auch Pakete können über dieselbe API Diagnostics aus ihrem Service Provider heraus registrieren.

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

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

Im Report wird angezeigt, aus welchem Paket die Diagnostic stammt.

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

## Programmatische Ausführung

Sie können `Doctor::run()` auch direkt aufrufen, ohne den Artisan-Befehl zu verwenden.

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

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

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

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.

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

$report->fixes();
```

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

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

php artisan doctor --format=github
```

Wird über den [Laravel Agent Detector](https://github.com/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](https://github.com/laravel/pao) verwendet.

```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}]}
```

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.

<Card title="laravel/doctor Repository" icon="github" href="https://github.com/laravel/doctor">
  Quellcode und neueste Informationen hier.
</Card>


## Related topics

- [Laravel Pennant](/de/pennant.md)
- [Laravel Notification für Discord (Webhook)](/de/packages/laravel-notification-discord-webhook.md)
- [Verzeichnisstruktur](/de/directory-structure.md)
- [Erste Schritte - GitHub Copilot SDK für Laravel](/de/packages/laravel-copilot-sdk/getting-started.md)
- [Laravel Pulse](/de/pulse.md)