Laravel Self Diagnosis Laravel Package

Product Decisions This Supports

• Turning "is this environment correctly configured?" into an executable release gate. The package converts a checklist that normally lives in a senior engineer's head — PHP version, required extensions, writable directories, .env presence, app key, storage symlink, database connectivity — into a repeatable pass/fail surfaced through php artisan diagnose and a web dashboard. As a PM, that is the artifact you can attach to a launch review and point to afterward: a go/no-go backed by output rather than memory.
• An honest build-vs-buy-vs-adopt framing. Three options exist: adopt this package (an afternoon of integration), hand-roll an Artisan command (days of work plus permanent ownership of an evolving check list across framework majors), or buy a monitoring/observability product (real annual spend). This package sits at the low end of that spectrum and is the right answer when the question is "verify configuration," not "watch the system." Keeping that distinction explicit prevents a diagnostics dependency from being quietly re-scoped into a monitoring purchase.
• A support-cost lever, not just a developer convenience. A meaningful share of Laravel support load is misconfiguration rather than code defect: stale config cache, non-writable storage, wrong app key, missing symlink, unreachable database. A single diagnostic surface shortens "the app is broken" to "we know which subsystem is failing," and lets support agents run the check before escalating. Treat it as a triage tool and instrument it — tickets deflected, time-to-triage — so the value is measured rather than asserted.
• A product feature for self-hosted and on-prem installs. If customers install our software themselves, a "run diagnostics" page is a capability we would otherwise scope, design, and maintain. Here it is an integration task. On a roadmap where install friction competes directly with new capability, that is a strong trade.
• Roadmap signal — framework currency. The 3.1.0 headline is Laravel 13.x compatibility, delivered as a minor, non-breaking release from 3.0.0 with no deprecations or migration work. For planning, that means the dependency tracks upstream majors rather than pinning to a past one, so it can stay in place through our next Laravel upgrade instead of being scheduled for replacement alongside it.
• Green-light use cases: internal, dev, and staging diagnostics; pre-launch checklists; deploy-pipeline smoke checks via the Artisan command; onboarding engineers to an environment's expected state; an authenticated, customer-facing diagnostics page for self-hosted installs.
• Explicit gate-or-decline decision: exposing the HTTP route unauthenticated in production. The page renders environment detail — PHP version, extension inventory, filesystem layout — to anyone who can load it. The access policy (auth middleware, IP allowlist, or environment-gated off) is our decision, not the package's, and it must be made before this ships anywhere a customer or scanner can reach it.

When to Consider This Package

Adopt when most of these hold:

• You run Laravel on a supported major. 3.1.0 covers Laravel 13.x, but verify your exact PHP/Laravel pairing against the package's composer.json rather than inferring it from the changelog or CI matrix.
• The question you need answered is "is this app correctly configured and provisioned right now?" — not "has this app met its SLO over the last 30 days?"
• You want a low-ceremony surface: a web dashboard for humans and an Artisan command for pipelines, not an observability stack.
• You can control access to the output, and you will assign that gating work an owner rather than treating it as an afterthought.
• You are comfortable with a small, single-maintainer-lineage dependency in a non-critical path. The correct risk posture is that it can be removed in an afternoon: one service provider, one config file, no migrations, no schema, no background jobs.
• You will actually run it. Wire the command into a post-deploy smoke step; installed-but-never-executed is the standard failure mode of this adoption.

Look elsewhere, or supplement, when:

• You need continuous monitoring, alerting, historical trends, or on-call escalation. This package reports state when asked; it watches nothing. That is a separate product category and a separate buying decision.
• You need deeper runtime health semantics — queue depth and worker liveness, scheduler heartbeat, cache hit rates, third-party latency, business KPIs. Spatie's Laravel Health is the usual comparison point for a broader check framework. A reasonable plan is this package for environment correctness plus a purpose-built framework for runtime semantics.
• You are not on Laravel, or you are pinned to a major the package has dropped.
• You require auditability, structured logs, or compliance-grade evidence of environment state. Output here is operator-facing, not an audit trail.
• Your security model cannot tolerate the endpoint existing at all, even disabled. If so, run it purely as a CLI deploy step, or build the equivalent yourself.
• Maintenance runway outweighs convenience. Upkeep currently appears driven largely by automated compatibility PRs, and the second 3.1.0 entry ("Dev by @mechelon") is too opaque to evaluate. Not a blocker for a minor bump, but plan the exit rather than assuming a patch lands the day a future Laravel major ships.

On 3.1.0 specifically: minor and non-breaking from 3.0.0, no migration work. Pin to the tag rather than a branch, schedule it with a routine dependency update, and diff any already-published config/self-diagnosis.php against the vendor copy afterward — Laravel's merged config applies new keys silently, which is convenient but can hide a changed default.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, free, open-source add-on for our Laravel application that turns "is this environment set up correctly?" from a manual checklist and a support ticket into an automated check with a clear pass/fail view. Integration is measured in hours, not sprints, and it replaces work we would otherwise hand-build and maintain ourselves — check by check, framework release by framework release. Its latest release confirms support for the current Laravel generation, so it will not become an obstacle during our next framework upgrade. The decision that actually needs a sponsor is not whether to use it but who may see its output: we keep the diagnostic page internal or behind authentication and off by default in production. It is a readiness and triage convenience, not a monitoring or alerting system, and we should not present it to customers or the board as one.

For the engineering team:

• What it is: a Laravel package that registers a configurable set of self-diagnosis checks against an application environment and surfaces results through a web dashboard and an Artisan command. It answers "is this app correctly configured and provisioned right now," not "has this app been healthy over the last month."
• Why now: 3.1.0 adds Laravel 13.x compatibility — minor, non-breaking, low-risk from 3.0.0, no deprecations. Adopting and pinning now means one fewer dependency to negotiate during the Laravel 13 upgrade.
• Integration cost: an afternoon at most — Composer install, publish config, choose which checks matter to us, add custom checks where domain-specific preconditions exist, gate the route, wire the command into the deploy pipeline as a post-deploy smoke test.
• Explicit non-goals: not APM, not alerting, not a metrics store, not an audit log, not a substitute for queue, scheduler, or service-connectivity checks. If we want those, that is a separate scoping conversation.
• Action items before merge: (1) verify our PHP/Laravel versions against the package's actual composer.json constraints, not just its CI matrix — the realistic failure mode is a silent downgrade to an older tag during composer update; (2) gate the diagnostic route behind auth or an environment check, confirm the "off in production" path works, and document it in the runbook; (3) pin to tag 3.1.0, not a branch; (4) confirm a throwing check cannot take down the request path; (5) run the diagnostics once post-upgrade in the SAPI that matters — CLI and FPM can report different extension and ini state, so a green CLI run does not guarantee a green web run — and diff the output against 3.0.0.
• Open question for the adopting team: the changelog entry "Dev by @mechelon" is uninformative. Not a blocker for a minor release, but it is a reason to read the diff on minor bumps for this dependency rather than trusting release notes — and to confirm whether PR #123 touched checks, route middleware, or config defaults, and whether composer.json actually widened illuminate/* to admit ^13.0 rather than merely being tested against it.