Laravel Doctor: Health Checks With php artisan doctor | 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 is a first-party package announced at Laracon US 2026 that adds an `artisan doctor` command to run health checks across environment, database, cache, storage, security, and more. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 3 Aug 2026 · Updated 3 Aug 2026 · 4 min read ShareCopy linkCopied ![Laravel Doctor: Diagnose Your Laravel App With One Artisan Command](https://cdn.msaied.com/504/d72224689abc7b396bce187535008272.png) 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) 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) - [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) - [Laravel Doctor](https://www.msaied.com/public/articles?search=Laravel%20Doctor) - [DevOps](https://www.msaied.com/public/articles?search=DevOps) - [CI/CD](https://www.msaied.com/public/articles?search=CI%2FCD) Frequently asked questions --------------------------- 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. 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`. 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. ![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 articleLivewire v4.3.5 Released: Fix for SFC Detection with PHP Attribute Array Arguments](https://www.msaied.com/public/articles/livewire-v435-released-fix-for-sfc-detection-with-php-attribute-array-arguments-1) [Next 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) 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) ### 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)