Laravel Doctor: App Health Checks via Artisan | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ home ](https://www.msaied.com) [ articles ](https://www.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://www.msaied.com/articles?category=laravel) [ Composer Pacakge ](https://www.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%2Fwww.msaied.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%2Fwww.msaied.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://www.msaied.com/articles) [ ![Saga Lara Flow: Durable Workflows and Compensating Transactions on Laravel Queues](https://cdn.msaied.com/520/d77bd3c0cecb6fb89c16f85648e7e369.png) Laravel Workflows Saga Pattern ### Saga Lara Flow: Durable Workflows and Compensating Transactions on Laravel Queues Saga Lara Flow is a Laravel package that lets you write long-running business processes as plain PHP methods o... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 7 Aug 2026 4 min read Read ](https://www.msaied.com/articles/saga-lara-flow-durable-workflows-and-compensating-transactions-on-laravel-queues) [ ![Filament v4.12 & v5.7: Major Performance Improvements and Security Patches](https://cdn.msaied.com/518/48e5a4da1b38d6cf27a0117baa547e1b.png) Filament Laravel Performance ### Filament v4.12 & v5.7: Major Performance Improvements and Security Patches Filament v4.12.6 and v5.7.6 ship massive rendering speed gains—up to 92% faster form fields—alongside security... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 6 Aug 2026 1 min read Read ](https://www.msaied.com/articles/filament-v412-v57-major-performance-improvements-and-security-patches) [ ![Managed Queues: Autoscaling Queue Workers on Laravel Cloud](https://cdn.msaied.com/519/854099015015dbc72dd8743202b69efc.png) Laravel Cloud Queue Workers Autoscaling ### Managed Queues: Autoscaling Queue Workers on Laravel Cloud Laravel Cloud's managed queues feature autoscales workers based on queue pressure, surfaces failed jobs in a r... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 6 Aug 2026 3 min read Read ](https://www.msaied.com/articles/managed-queues-autoscaling-queue-workers-on-laravel-cloud) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.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://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [Contact](https://www.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)