Laravel Just Added the Health Check Your CI Was Missing

Most failed deployments are not caused by an exotic framework bug. They come from an ordinary mismatch: a missing PHP extension, an invalid environment value, an absent application key, a stale cache, or a worker running code with different assumptions from the web process. Laravel’s newly announced artisan doctor command turns those assumptions into explicit diagnostics. It can inspect application health, fix selected problems automatically, and accept checks registered by packages. The viral headline is “one command finds your config mistakes.” The engineering opportunity is better: make readiness a versioned contract that runs locally, in CI, during deployment, and after infrastructure changes.

A doctor check is not a test suite

Unit and feature tests prove behavior under controlled conditions. Static analysis evaluates code. A doctor check asks whether this particular installation has what the application needs to run. The categories overlap, but they fail for different reasons and belong at different stages.

Keep diagnostics fast and deterministic. Checking whether an extension exists or a required environment variable is present is appropriate. Calling a flaky third-party API on every local run is not. Network dependency checks belong in a separately labeled mode with clear timeouts.

Turn undocumented assumptions into checks

Interview the people who deploy and support the application. Every sentence beginning with “remember to” is a candidate: remember to enable Redis, create the storage link, configure a queue connection, install an image codec, set the webhook secret, or use the supported database version.

• State the requirement in plain language.
• Detect it without exposing secrets.
• Explain the exact remediation.
• Mark whether failure blocks production or only disables a feature.
• Link the check to an owner and a test.

Let packages diagnose themselves

The command becomes much more useful when packages register their own checks. A billing package understands its webhook and currency requirements better than the host application. A media package knows which binary and writable path it needs. Package-owned diagnostics keep operational knowledge next to the code that changes it.

Avoid turning the doctor into advertising or a wall of green messages. Register checks only for real runtime requirements, group them sensibly, and make optional recommendations visibly different from failures.

Use safe automatic fixes

Automatic remediation is valuable for reversible, local changes such as creating a missing public storage link or generating a development-only file. It is risky when a fix rotates credentials, edits production data, changes permissions broadly, or installs system packages. Require explicit confirmation for material changes and show what will happen first.

In CI, checks should report rather than mutate. A pipeline that silently repairs its own runner may pass while production remains misconfigured. The build should fail with a precise message that leads to an infrastructure change committed in the correct place.

Run it at four useful moments

First, run diagnostics after a developer checks out the repository. Second, run them in CI against the container or build image. Third, run them during deployment after secrets and services are attached but before traffic shifts. Fourth, run them after major infrastructure changes or incident recovery.

These stages do not need identical profiles. Local development may accept a file cache; production may require Redis. Represent environment-specific requirements explicitly instead of burying branches inside vague checks.

Make failures actionable and secure

A good result names the broken requirement, detected state, expected state, and safe next command or documentation page. A bad result prints an exception or dumps configuration. Never echo secret values to prove they exist. Show presence, format validity, or a short fingerprint when comparison is necessary.

Emit machine-readable status for CI and human-readable guidance for operators. Stable check identifiers let teams suppress a deliberate exception with an expiry date instead of ignoring the whole tool.

Build a readiness contract now

Start with ten checks that cover the incidents and onboarding mistakes your team has actually seen. Run them in a non-production environment, tune false positives, and make only truly critical failures block deployment. Expand the catalog when a new incident reveals an unstated assumption.

Laravel introduced Artisan doctor in the Laracon US 2026 announcement roundup. The command will not replace monitoring or tests. It closes the gap between “the code is correct” and “this installation is ready,” which is exactly where many expensive surprises live.

Version the diagnostic contract

Checks evolve with the application. Add stable identifiers and include the application commit or release in diagnostic output so operators know which requirements were evaluated. When a new check becomes mandatory, introduce it as a warning first if existing environments need time to comply.

Store a compact result with each deployment: check ID, status, duration, and remediation reference. That record can answer whether a later incident began with a known warning without preserving sensitive configuration. It also shows which checks are slow or flaky enough to undermine trust in the command.

Photo by Al Nahian on Pexels.