Laravel Doctor: App Health Checks via Artisan | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Laravel Doctor: Diagnose Your Laravel App With One Artisan Command 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) ![Laravel Doctor: Diagnose Your Laravel App With One Artisan Command](https://cdn.msaied.com/513/2550bf2c87d0df242beb6ed7fe4df5d5.png) [ Laravel ](https://msaied.com/articles?category=laravel) [ Composer Pacakge ](https://msaied.com/articles?category=composer-pacakge) #Laravel #Artisan #Health Checks #DevOps #Laravel Doctor Laravel Doctor: Diagnose Your Laravel App With One Artisan Command ==================================================================== 3 Aug 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 What Is Laravel Doctor? ](#what-is-laravel-doctor) 2. [ 02 What Gets Checked ](#what-gets-checked) 3. [ 03 Automatic Fixes ](#automatic-fixes) 4. [ 04 Filtering Diagnostics ](#filtering-diagnostics) 5. [ 05 Custom and Package Diagnostics ](#custom-and-package-diagnostics) 6. [ 06 CI, GitHub Actions, and AI Agents ](#ci-github-actions-and-ai-agents) 7. [ 07 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)* Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Flaravel-doctor-diagnose-your-laravel-app-with-one-artisan-command-1&text=Laravel+Doctor%3A+Diagnose+Your+Laravel+App+With+One+Artisan+Command) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Flaravel-doctor-diagnose-your-laravel-app-with-one-artisan-command-1) Frequently Asked Questions ---------------------------- 3 questions Q01 What PHP and Laravel versions does Laravel Doctor require? Laravel Doctor requires PHP 8.3 and either Laravel 12 or Laravel 13. Q02 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`. Q03 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. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Official Laravel Zed Extension: LSP Support for PHP and Blade Files](https://cdn.msaied.com/511/9a507c942d0051cc70a4c6769b27f734.png) Laravel Zed LSP ### Official Laravel Zed Extension: LSP Support for PHP and Blade Files The Laravel team has released an official Zed extension (v0.1.0) that wires Laravel LSP into the editor, bring... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 4 Aug 2026 3 min read Read ](https://msaied.com/articles/official-laravel-zed-extension-lsp-support-for-php-and-blade-files) [ ![Laravel Head: Manage Meta Tags, Open Graph, and JSON-LD in Laravel 13](https://cdn.msaied.com/512/4b4bedfc34f26b38c69fed3a3b5813e9.png) Laravel SEO Open Graph ### Laravel Head: Manage Meta Tags, Open Graph, and JSON-LD in Laravel 13 Laravel Head is a new first-party package that gives you a fluent API for titles, meta descriptions, Open Grap... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 4 Aug 2026 4 min read Read ](https://msaied.com/articles/laravel-head-manage-meta-tags-open-graph-and-json-ld-in-laravel-13) [ ![PostgreSQL CTEs, Window Functions, and Lateral Joins in Laravel](https://cdn.msaied.com/506/7d5fcddaf6c26c87a749a20b8bdffbfa.png) laravel postgresql sql ### PostgreSQL CTEs, Window Functions, and Lateral Joins in Laravel Go beyond basic Eloquent queries. Learn how to leverage PostgreSQL CTEs, window functions, and LATERAL joins d... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 4 Aug 2026 1 min read Read ](https://msaied.com/articles/postgresql-ctes-window-functions-and-lateral-joins-in-laravel-4) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)