Laravel Doctor: App Health Checks via Artisan | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public) - [Projects](https://www.msaied.com/public/projects) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [About](https://www.msaied.com/public#about) [ Contact](https://www.msaied.com/public#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com/public) - [ProjectsCase studies](https://www.msaied.com/public/projects) - [ArticlesEngineering notes](https://www.msaied.com/public/articles) - [CertificatesCredentials](https://www.msaied.com/public/certificates) - [AboutHow I work](https://www.msaied.com/public#about) - [ContactGet in touch](https://www.msaied.com/public#contact) [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com/public) 2. / 3. [Articles](https://www.msaied.com/public/articles) 4. / 5. [Laravel](https://www.msaied.com/public/articles?category=laravel) 6. / 7. Laravel Doctor: Diagnose Your Laravel App With One Artisan Command [Laravel](https://www.msaied.com/public/articles?category=laravel) [Composer Pacakge](https://www.msaied.com/public/articles?category=composer-pacakge) Laravel Doctor: Diagnose Your Laravel App With One Artisan Command =================================================================== Laravel Doctor, announced at Laracon US 2026, adds an `artisan doctor` command that runs comprehensive health checks against your Laravel application and can automatically fix common issues. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 3 Aug 2026 · Updated 5 Aug 2026 · 4 min read ShareCopy linkCopied ![Laravel Doctor: Diagnose Your Laravel App With One Artisan Command](https://cdn.msaied.com/513/2550bf2c87d0df242beb6ed7fe4df5d5.png) On this page +1. [What Is Laravel Doctor?](#what-is-laravel-doctor) 2. [What Gets Checked](#what-gets-checked) 3. [Automatic Fixes](#automatic-fixes) 4. [Filtering Diagnostics](#filtering-diagnostics) 5. [Custom and Package Diagnostics](#custom-and-package-diagnostics) 6. [CI, GitHub Actions, and AI Agents](#ci-github-actions-and-ai-agents) 7. [Key Takeaways](#key-takeaways) What Is Laravel Doctor? ----------------------- Announced at Laracon US 2026 in Boston, [Laravel Doctor](https://github.com/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: ```bash composer require laravel/doctor --dev ``` Then run it: ```bash 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: ```yaml 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 --------------------- ```bash php artisan doctor --only=security php artisan doctor --except=laravel/* ``` Publish the config file to make selectors permanent: ```bash php artisan vendor:publish --tag=doctor-config ``` Custom and Package Diagnostics ------------------------------ Packages register their own checks via the `Doctor` facade in a service provider: ```php use Laravel\Doctor\Facades\Doctor; use Vendor\Package\Diagnostics\HorizonIsRunning; public function boot(): void { Doctor::diagnostic(HorizonIsRunning::class); } ``` Scaffold a new diagnostic with: ```bash 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](https://github.com/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](https://laravel-news.com/laravel-doctor-first-party-diagnostics-for-your-application)* - [Laravel](https://www.msaied.com/public/articles?search=Laravel) - [Artisan](https://www.msaied.com/public/articles?search=Artisan) - [Health Checks](https://www.msaied.com/public/articles?search=Health%20Checks) - [DevOps](https://www.msaied.com/public/articles?search=DevOps) - [Laravel Doctor](https://www.msaied.com/public/articles?search=Laravel%20Doctor) Frequently asked questions --------------------------- What PHP and Laravel versions does Laravel Doctor require?Laravel Doctor requires PHP 8.3 and either Laravel 12 or Laravel 13. Can Laravel Doctor automatically fix issues it finds?Yes. Running `php artisan doctor --fix` auto-repairs issues such as a missing `.env` file, a missing `APP\_KEY`, incorrect storage permissions, and the public storage symlink. Issues that require a human choice — like selecting a different cache driver — are presented as an interactive select list and are not applied automatically under `--fix`. How can third-party packages add their own checks to Laravel Doctor?Packages register diagnostics from their service provider using the `Doctor` facade: `Doctor::diagnostic(MyCheck::class)`. The `php artisan make:diagnostic` command scaffolds the required class structure, and implementing `Laravel\\Doctor\\Contracts\\Fixable` adds optional auto-repair support. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articlePhpStorm 2026.2 Released: Laravel Tool Window, PHP 8.5 Pipe Operator, and AI Agents](https://www.msaied.com/public/articles/phpstorm-20262-released-laravel-tool-window-php-85-pipe-operator-and-ai-agents-1) [Next articlePostgreSQL CTEs, Window Functions, and Lateral Joins in Laravel](https://www.msaied.com/public/articles/postgresql-ctes-window-functions-and-lateral-joins-in-laravel-4) On this page ------------- 1. [What Is Laravel Doctor?](#what-is-laravel-doctor) 2. [What Gets Checked](#what-gets-checked) 3. [Automatic Fixes](#automatic-fixes) 4. [Filtering Diagnostics](#filtering-diagnostics) 5. [Custom and Package Diagnostics](#custom-and-package-diagnostics) 6. [CI, GitHub Actions, and AI Agents](#ci-github-actions-and-ai-agents) 7. [Key Takeaways](#key-takeaways) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com/public#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/740/cce86edc21eddcbdd2f2454fadaf9c70.png) · 3 min read### The Pipeline Pattern in Laravel: Custom Pipelines Beyond Middleware 5 Oct 2026 ](https://www.msaied.com/public/articles/the-pipeline-pattern-in-laravel-custom-pipelines-beyond-middleware-1) [ ![](https://cdn.msaied.com/739/2d6897fdcdcf090613f96f72a64b8a78.png) · 4 min read### MySQL Full-Text Search in Laravel: Indexes, Relevance Scoring, and Boolean Mode 4 Oct 2026 ](https://www.msaied.com/public/articles/mysql-full-text-search-in-laravel-indexes-relevance-scoring-and-boolean-mode) [ ![](https://cdn.msaied.com/738/073696a3fefe18bec825beec5ac658f5.png) · 4 min read### Laravel Queue Rate-Limited Middleware: Throttling Jobs Without Losing Work 4 Oct 2026 ](https://www.msaied.com/public/articles/laravel-queue-rate-limited-middleware-throttling-jobs-without-losing-work) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com/public#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com/public) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/public/sitemap.xml)