Laravel Doctor: Health Checks With php artisan doctor | 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. [ How the Diagnostic System Works ](#how-the-diagnostic-system-works) 3. [ Built-in Check Categories ](#built-in-check-categories) 4. [ Getting Started ](#getting-started) 5. [ Writing Custom Diagnostics ](#writing-custom-diagnostics) 6. [ CI, GitHub Actions, and AI Agent Output ](#ci-github-actions-and-ai-agent-output) 7. [ Key Takeaways ](#key-takeaways) ![Laravel Doctor: Diagnose Your Laravel App With One Artisan Command](https://cdn.msaied.com/504/d72224689abc7b396bce187535008272.png) [ Laravel ](https://msaied.com/articles?category=laravel) [ Composer Pacakge ](https://msaied.com/articles?category=composer-pacakge) #Laravel #Artisan #Health Checks #Laravel Doctor #DevOps #CI/CD 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 How the Diagnostic System Works ](#how-the-diagnostic-system-works) 3. [ 03 Built-in Check Categories ](#built-in-check-categories) 4. [ 04 Getting Started ](#getting-started) 5. [ 05 Writing Custom Diagnostics ](#writing-custom-diagnostics) 6. [ 06 CI, GitHub Actions, and AI Agent Output ](#ci-github-actions-and-ai-agent-output) 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 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: ```bash composer require laravel/doctor --dev ``` Then run: ```bash php artisan doctor ``` When a fixable issue is found, Doctor prompts before acting: ```yaml 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`: ```bash php artisan doctor --only=security php artisan doctor --except=laravel/* ``` Publish the config to make selectors permanent: ```bash php artisan vendor:publish --tag=doctor-config ``` Writing Custom 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 ``` 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](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 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](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&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) Frequently Asked Questions ---------------------------- 3 questions Q01 What does `php artisan doctor` check in a Laravel application? It checks environment configuration (`.env`, `APP_KEY`, PHP version, extensions), Composer dependencies, config loading, database connectivity, pending migrations, cache and queue driver reachability, storage writability, and security settings such as debug mode and `.env` being git-ignored. Q02 Can Laravel Doctor automatically fix the issues it finds? Yes. Running `php artisan doctor --fix` skips interactive prompts and automatically repairs issues such as a missing `.env`, an unset `APP_KEY`, incorrect storage permissions, a missing public storage symlink, and debug mode being enabled in production. Issues that require a human choice — like selecting a replacement cache driver — are presented as a select list interactively and fall back to ordinary failures under `--fix`. Q03 How do I add custom diagnostics for my own package? Register your diagnostic class via the `Doctor` facade in your service provider's `boot()` method: `Doctor::diagnostic(MyCheck::class)`. Scaffold the class with `php artisan make:diagnostic MyCheck`. It extends `Laravel\Doctor\Diagnostic`, implements a `check()` method returning a `DiagnosticResult`, and optionally implements `Laravel\Doctor\Contracts\Fixable` for auto-repair support. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![PhpStorm 2026.2 Released: Laravel Tool Window, PHP 8.5 Pipe Operator, and AI Agents](https://cdn.msaied.com/505/151a0bba66cc27064e090e69e55d7c92.png) PhpStorm JetBrains PHP 8.5 ### PhpStorm 2026.2 Released: Laravel Tool Window, PHP 8.5 Pipe Operator, and AI Agents PhpStorm 2026.2 ships a dedicated Laravel tool window with Artisan, error logs, and Laravel Cloud tabs, plus P... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 3 Aug 2026 3 min read Read ](https://msaied.com/articles/phpstorm-20262-released-laravel-tool-window-php-85-pipe-operator-and-ai-agents) [ ![Livewire v4.3.5 Released: Fix for SFC Detection with PHP Attribute Array Arguments](https://cdn.msaied.com/503/9678ed8dbf5d7a6f4f19ca7694cf241b.png) Livewire Laravel PHP ### Livewire v4.3.5 Released: Fix for SFC Detection with PHP Attribute Array Arguments Livewire v4.3.5 ships a targeted bug fix for Single File Component (SFC) detection when PHP attributes contain... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 3 Aug 2026 2 min read Read ](https://msaied.com/articles/livewire-v435-released-fix-for-sfc-detection-with-php-attribute-array-arguments) [ ![Laravel Filament v3 Custom Actions: Bulk, Table, and Header Actions Done Right](https://cdn.msaied.com/502/ff034ec2bd69cdc8e56eced7a83882a3.png) filament laravel filament-actions ### Laravel Filament v3 Custom Actions: Bulk, Table, and Header Actions Done Right Go beyond the defaults: build type-safe bulk actions, inject services into header actions, and wire table row... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 3 Aug 2026 3 min read Read ](https://msaied.com/articles/laravel-filament-v3-custom-actions-bulk-table-and-header-actions-done-right) [ ![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)