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 adds a single Artisan command — php artisan doctor — to run a comprehensive suite of health checks against your Laravel application.

If you have ever debugged a broken install by mentally ticking off whether .env exists, whether APP_KEY is set, or whether storage/ is writable, Doctor turns that checklist into code.

How the Diagnostic System Works

Every check is a single class that inspects one thing and returns one of six statuses: pass, notice, warn, fail, skip, or error. The command exits with a non-zero code on failures or errors by default.

• Use --fail-on=warn to also fail CI builds on warnings.
• Use --fail-on=never to get a report without ever failing the exit code.

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

Built-in Check Categories

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

Getting Started

Install as a dev dependency:

composer require laravel/doctor --dev

Then run:

php artisan doctor

When a fixable issue is found, Doctor prompts before acting:

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

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

Skip prompts entirely with --fix. Automatic repairs include creating a missing .env, generating APP_KEY, disabling debug mode in production, adding .env to .gitignore, creating the public storage symlink, and fixing storage permissions.

Filter checks with --only or --except:

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

Publish the config to make selectors permanent:

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

Writing Custom 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

This creates a class in app/Doctor/Diagnostics that extends Laravel\Doctor\Diagnostic and implements a check() method returning a DiagnosticResult. If the check can repair what it finds, implement Laravel\Doctor\Contracts\Fixable and mark failures with ->fixable().

CI, GitHub Actions, and AI Agent Output

Doctor supports multiple output formats:

• --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 listed. Re-running with --fix applies repairs and appends updated outcomes to the payload.

Doctor can also run programmatically without Artisan: Doctor::run() returns a DiagnosticReport, with only(), except(), bail(), and fixUsing() available for programmatic control.

Key Takeaways

• php artisan doctor runs a full health check suite covering environment, database, cache, storage, and security
• Six result statuses with environment-aware pass/fail logic (local vs. production)
• --fix flag auto-repairs common issues without prompting
• Packages can register custom diagnostics via the Doctor facade
• JSON, GitHub Actions, and AI agent output formats are built in
• Requires PHP 8.3 and Laravel 12 or 13; MIT licensed

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