The Php Times

Laravel Doctor, unveiled at Laracon US 2026 in Boston, is a new first-party package that adds an artisan doctor command to diagnose application health. It covers the classic broken-install checklist — missing .env, absent APP_KEY, unwritable storage, PHP version mismatches — and turns it into executable code. Packages can also register their own checks.

Each diagnostic is a class inspecting one thing and returning one of six statuses: pass, notice, warn, fail, skip, or error. The command exits non-zero on failures or errors; --fail-on=warn makes warnings fail too, while --fail-on=never always returns a clean exit code.

The bundled suite spans environment (.env presence, APP_KEY, PHP version vs. the composer.json constraint, extensions, timezone), Composer (dependencies installed, optimized autoload dump, repairable composer.lock problems), configuration, database connectivity including SQLite files and pending migrations, cache/queue/scheduler/session driver reachability (with Redis checks), storage writability and the storage:link symlink, and security (debug mode vs. environment, .env in .gitignore, dependency audits). Doctor resolves the app into local or production mode — staging is known, unknown environments are treated as production — so a sync queue passes locally but warns in production, and bootstrap caches behave accordingly.

Installation is composer require laravel/doctor --dev, then php artisan doctor. Fixable problems prompt interactively, and php artisan doctor --fix applies repairs automatically: creating a missing .env, generating APP_KEY, disabling debug in production, gitignoring .env, creating the storage link, and fixing permissions. Diagnostics can be filtered with --only/--except by group, class, or package wildcard (e.g. --except=laravel/*), or persisted via php artisan vendor:publish --tag=doctor-config.

Packages register diagnostics through the Doctor facade in their service provider, and php artisan make:diagnostic scaffolds a custom check extending Laravel\Doctor\Diagnostic with a check() method; messages() holds summaries, remediation text, docs links, and fix prompts. Implementing Laravel\Doctor\Contracts\Fixable plus ->fixable() tags repairs, optionally limited to an EnvironmentMode.

Beyond CLI output, --format=json gives machine-readable reports and --format=github produces GitHub Actions annotations; both reject --fix. A fourth format follows the Laravel PAO convention — one line of JSON with counts up front — and activates automatically when Laravel Agent Detector senses Claude Code, Cursor, or similar agents, making artisan doctor a natural final sanity check for AI coding agents. Doctor::run() also works programmatically with only(), except(), bail(), and fixUsing().

Laravel Doctor requires PHP 8.3 and Laravel 12 or 13, is MIT licensed, and is documented on the laravel/doctor GitHub repository.