Doctor Laravel Package

Product Decisions This Supports

• Developer onboarding velocity. A single php artisan doctor run replaces a wiki page of "why won't my app boot" checks (.env missing, APP_KEY absent, storage not writable, broken symlink, PHP extensions). Directly reduces time-to-first-commit for new hires and the support load on senior engineers.
• CI/CD gating and release readiness. Distinct pass / notice / warn / fail / skip / error statuses plus --fail-on=warn and --bail make this a deploy gate, not just a linter. The exit-code contract lets you enforce "no debug mode in production," "queues are async," "bootstrap cache present" before traffic lands.
• Build vs. buy for internal health checks. If you have a bespoke app:healthcheck command, this is the replacement candidate. The Diagnostic base class, make:diagnostic scaffold, and --only / --except selection by class, group, or package mean custom org-specific checks (Horizon running, CDN reachable, feature flag service up) slot in without forking.
• Environment-aware policy, not just messaging. The local vs production mode split is the key product idea: the same fact (sync queue, uncached config, debug on) is correct in one mode and dangerous in the other. This lets you ship one tool to laptops and to prod without two config files or "ignore these warnings" culture.
• Safe automation vs. human judgment. Fixes require an explicit Fixable contract plus ->fixable(EnvironmentMode::Local) scoping, and --fix deliberately refuses to prompt while JSON/GitHub reporters refuse --fix entirely. That's a defensible safety posture you can put in front of a security reviewer.
• Agent and tooling strategy. Agent output with a structured fixes array and versionless docs links that resolve to .md for machines signals an intended use as a tool inside AI coding agents — relevant if your roadmap includes AI-assisted dev environments or automated environment repair.
• Roadmap signal. A first-party diagnostics primitive from the Laravel core team suggests the framework is formalizing "operational correctness" as a first-class concern; expect adjacent first-party packages and growing relevance for platform teams standardizing on Laravel.

When to Consider This Package

Adopt when:

• You run Laravel and want a low-effort, zero-runtime-footprint baseline (--dev only) for environment and configuration validation.
• You have heterogeneous environments (local, staging, QA, prod) and need one policy with per-mode verdicts via the environments config map.
• You want CI enforcement of production hygiene — debug mode, async queues, cached bootstrap, .env in .gitignore, Composer audit — without writing or maintaining those checks.
• You're willing to extend it: the custom-diagnostic surface is small and well-documented, and the payoff scales with how many org-specific checks you add.
• You want fix automation that is deterministic and scoped to developer machines, with a clean audit trail (fixes array, stable machine-readable codes like application-key-is-set.missing).

Look elsewhere or wait when:

• Low-adoption risk is unacceptable. 111 stars and zero tracked dependents means near-zero external battle-testing. It's first-party and MIT, which mitigates abandonment risk, but not immaturity risk. Pin an exact version and expect churn in diagnostics and output formats.
• You need unattended remediation in production. --fix skips any fix requiring a choice, and machine-readable formats refuse fixing outright. If you need fully automated prod repair, this is not that tool.
• Your infrastructure is heavily customized. Non-conventional directory layouts, non-standard environment names, or a database/queue topology the default suite doesn't model will mean writing diagnostics yourself — at which point you're buying a runner and result model, not a check suite.
• You need observability, not preflight. This is a point-in-time preflight check, not runtime APM, tracing, or alerting. Don't pitch it as monitoring.
• You're polyglot. The value is Laravel-idiomatic; for multi-framework standardization, a vendor-neutral health-check convention is a better long-term bet.
• You need a stable public API contract. Pre-1.0 style churn plus fresh release cadence means programmatic Doctor::bail()->run() usage should be treated as experimental.

How to Pitch It (Stakeholders)

For executives: Laravel Doctor is a first-party, MIT-licensed diagnostic command that catches the misconfigurations that cause most "it works on my machine" incidents and most production security footguns — missing app keys, unwritable storage, debug mode left on in production, synchronous queues under live traffic, stale config caches. It installs as a dev dependency, so it adds nothing to production runtime, and it reduces onboarding friction and senior-engineer support load while giving us a deploy-time gate we control. It is early — low adoption, frequent releases — so the recommendation is a scoped pilot in one or two services, pinned to a version, with the CI gate enabled in report-only mode first. Cost is near zero; the upside is standardizing environment correctness without building and maintaining our own checker.

For engineering: It's a dev-only Composer package exposing php artisan doctor. Each check is a class returning a typed status (pass/notice/warn/fail/skip/error), with environment modes (local vs production) changing the verdict, not just the wording — so sync queues warn in prod and pass locally. Exit codes are meaningful: default fails on fail/error, --fail-on=warn tightens it, --fail-on=never for report-only, --bail for fast feedback. Selection is by class, group, package, or wildcard, layered on top of a published config file where configured only acts as an allowlist and except selectors merge. Auto-repair is opt-in: implement Fixable, mark the failure ->fixable(), optionally scope to EnvironmentMode::Local; --fix never prompts and applies only deterministic fixes, and both JSON and GitHub reporters reject --fix so machine output can't mutate an app. The real leverage is make:diagnostic — our own checks (Horizon, feature flags, CDN reachability) become first-class citizens alongside the built-ins with stable result codes for downstream tooling. Two caveats for the design review: the package is young (111 stars, no tracked dependents) so pin versions and avoid hard-coupling to programmatic APIs; and the built-in suite assumes conventional Laravel layout — budget a day for the first org-specific diagnostics before committing broadly.