Laravel Doctor: Diagnose Your Laravel App With One Artisan Command

What Is Laravel Doctor?

Announced at Laracon US 2026 in Boston, Laravel Doctor is a first-party package that brings a single artisan doctor command to your Laravel application. It runs a structured suite of health checks and, where possible, repairs problems automatically.

Install it as a dev dependency:

composer require laravel/doctor --dev

Then run it:

php artisan doctor

What Gets Checked

Each diagnostic is a class that inspects one concern and returns one of six statuses: pass, notice, warn, fail, skip, or error. The built-in suite covers seven areas:

• Environment — .env presence, APP_KEY, PHP version vs. composer.json, required extensions, timezone
• Composer — dependencies installed, autoload optimisation, composer.lock integrity
• Configuration — config loading, cache state, required driver values
• Database — connection reachability, SQLite file existence, pending migrations
• Cache, queue, scheduler, and session — driver reachability, Redis connections, scheduled tasks
• Storage — disk reachability, writable directories, storage:link symlink
• Security — debug mode vs. environment, .env in .gitignore, dependency audit

Doctor resolves your app into a local or production mode and adjusts expectations accordingly. A sync queue connection passes locally but warns in production. Unrecognised environments are held to production standards.

Automatic Fixes

When a failing check is repairable, Doctor prompts you before acting:

Storage is writable: The application cannot write to every required storage directory.

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

Pass --fix to skip prompts entirely. Doctor can create a missing .env, generate APP_KEY, disable debug mode in production, add .env to .gitignore, create the public storage symlink, and repair storage permissions. Choices that require human judgement — such as which cache store to switch to — appear as a select list interactively and fall back to ordinary failures under --fix.

Filtering Diagnostics

php artisan doctor --only=security
php artisan doctor --except=laravel/*

Publish the config file to make selectors permanent:

php artisan vendor:publish --tag=doctor-config

Custom and Package Diagnostics

Packages register their own checks via the Doctor facade in a service provider:

use Laravel\Doctor\Facades\Doctor;
use Vendor\Package\Diagnostics\HorizonIsRunning;

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

Scaffold a new diagnostic with:

php artisan make:diagnostic HorizonIsRunning

The generated class extends Laravel\Doctor\Diagnostic, implements a check() method returning a DiagnosticResult, and keeps user-facing wording in a separate messages() method. Implement Laravel\Doctor\Contracts\Fixable to add repair logic.

CI, GitHub Actions, and AI Agents

Doctor ships three output formats beyond the default CLI view:

• --format=json — machine-readable report
• --format=github — GitHub Actions annotations
• Agent format — activated automatically when Laravel Agent Detector detects a coding agent such as Claude Code or Cursor

The agent format follows the Laravel PAO convention — one line of JSON with counts up front and only actionable issues itemised. Test it locally with AI_AGENT=test php artisan doctor.

Doctor also exposes a programmatic API: Doctor::run() returns a DiagnosticReport, and only(), except(), bail(), and fixUsing() constrain the run without touching the CLI.

Key Takeaways

• php artisan doctor runs a full health check suite covering env, Composer, config, database, storage, and security
• Six diagnostic statuses with environment-aware pass/fail logic (local vs. production)
• --fix auto-repairs common issues; interactive prompts handle decisions that need human input
• --format=json and --format=github support CI pipelines; an agent-optimised format supports AI coding tools
• Packages can register their own diagnostics via the Doctor facade
• Requires PHP 8.3 and Laravel 12 or 13; MIT licensed

Source: Laravel News — Laravel Doctor: Diagnose Your App With One Artisan Command