Debug Laravel Package

Product Decisions This Supports

• Tooling budget vs. roadmap budget. orchestra/debug is engineering enablement for a legacy Laravel 5.4 / Orchestra Platform codebase — it ships no customer-facing capability. The PM decision is to fund adoption from maintenance/tooling spend and keep it out of roadmap artifacts, sprint commitments, and launch plans entirely.
• Build vs. buy vs. use what we already have. The real question isn't "is this good?" — it's "does a Laravel 5.4/Orchestra team need an in-app profiler badly enough to take on an unmaintained dependency?" Score it against barryvdh/laravel-debugbar, Clockwork, Telescope, or plain Xdebug. This package's only defensible differentiator is zero-friction integration inside the Orchestra admin environment, not capability. With 0 dependents and no stars, there is no community validation to borrow — the case must be argued from our own context or not at all.
• The production-leak guardrail, which is a PM-ownable decision. Approve it strictly as a require-dev dependency that is physically absent from release artifacts via composer install --no-dev. That single constraint converts the biggest business risk — debug output rendering SQL bindings, config values, or env secrets to a real user in staging or production — into a build-pipeline guarantee rather than a config flag someone can flip by accident.
• Legacy-stack risk accounting. Every dependency added to a Laravel 5.4 codebase deepens commitment to that codebase. Adoption must ship with an explicit expiry: "revisit at the next Laravel upgrade; expected outcome is removal, not replacement." This keeps a tooling decision from quietly becoming a reason the upgrade slips.
• Incident-triage investment case. The measurable upside is developer hours in the debugging loop: open the slow page → read the timeline to find the hot phase → cross-reference queries in that phase to confirm the N+1. If the team regularly burns half-days on slow-page triage in the Orchestra admin, there's a defensible efficiency case. If they don't, there isn't — and the PM should say so.
• Standardize on exactly one profiler. A decision worth making once, at the PM level: pick a single sanctioned profiler and document when it's used. Two profilers registering overlapping query listeners or middleware double-collect and distort the exact timings you're trying to read — worse than having none, because it produces confidently wrong performance data.
• Scope-check the "Orchestra integration" claim. If the app is not on Orchestra Platform, the seamless-integration pitch is inapplicable and we're adding a dependency for something Debugbar already does better. Verify this before the cost lands.

When to Consider This Package

• Consider it when the team maintains a Laravel 5.4 / Orchestra Platform application, works inside the Orchestra admin daily, and wants request timelines, query logging, and environment context without standing up external tooling.
• Consider it when the team values zero-friction integration over long-term support, and has accepted that Laravel 5.4 predates package auto-discovery — manual DebugServiceProvider registration in config/app.php is a mandatory setup step, not a bug.
• Consider it only as dev/staging tooling, with four conditions verified up front: the environment allowlist is fail-closed (local on, staging/production off), the environment panel doesn't expose secrets or connection strings, CI asserts the package is absent from production dependencies, and the version is pinned to ^3.4.
• Look elsewhere if the application is on Laravel 5.5+ or anything modern. Telescope, Debugbar, and Clockwork are maintained and supported; this package's compatible matrix is unproven beyond a single 5.4 compatibility bump in v3.4.0.
• Look elsewhere if the need is production observability, distributed tracing, security-sensitive diagnostics, vendor SLAs, or community support. This is a development companion, not an APM.
• Do not adopt on the strength of a release note alone, and do not adopt it as a reason to stay on Laravel 5.4. Before committing, confirm: does it pin illuminate/* to 5.4? License? Maintainer count? Does it hard-require Orchestra packages or run standalone? And critically — does it conflict with or suppress a profiler already in use?
• Treat "zero dependents" as a staffing assumption. We are the QA team. Regressions surface in our environment first with no upstream pressure to fix them; if this becomes load-bearing for debugging workflows, vendor a fork rather than wait.

How to Pitch It (Stakeholders)

• Executives: This is a low-cost, development-only diagnostic tool for our legacy Laravel 5.4/Orchestra application. It adds no customer-facing features and no revenue. It may reduce engineering hours lost to chasing slow requests and bad SQL, and — as importantly — the guardrails we're putting around it (dev-only dependency, environment-gated, absent from production builds) eliminate the one real business risk, which is debug output exposing database queries or credentials to a live user. Approve it as maintenance tooling with a defined expiry tied to the platform upgrade, not as a platform investment.
• Engineering: Install under require-dev pinned to ^3.4; no auto-discovery on 5.4, so register Orchestra\Debug\DebugServiceProvider manually and publish the config. Gate activation behind an env allowlist that defaults to off and is verified fail-closed by setting APP_ENV=production locally and confirming the panel doesn't render — before and after any config change. Work timeline-first, query-log second; reading a 200-query log without the timeline is how an afternoon disappears. Keep the integration behind a thin adapter (start()/mark()/log()) so swapping to Debugbar, Clockwork, or Telescope is a one-file change, verify mutual exclusivity with any existing profiler before standardizing, and expect the extension surface to be thin — custom panels mean writing against Debugbar's API, not this one's.
• Product: No roadmap, customer, or launch impact. This is engineering enablement for legacy support only — don't build requirements or commitments around it, and don't let it appear in planning artifacts. The PM's deliverable is the guardrails: dev-only, environment-gated, one profiler per app, version pinned, and a recorded expiry with a named owner.