Debug Laravel Package

Getting Started

orchestra/debug is developer tooling, not application code. Treat it as a require-dev dependency, gate it to local, and get one slow request profiled before you read another line of the README. The entire pay-off is a single loop: timeline → query log → confirm the N+1.

1. Check the framework matrix first. The only release with detail is v3.4.0, which is explicitly a Laravel 5.4 compatibility release. Inspect the illuminate/* constraints in the package's composer.json before you plan anything — do not assume it works on 5.5+, and do not assume the constraint is ^5.4; it may be pinned tighter than that.

   composer require --dev orchestra/debug:^3.4
   

   If the app is not on Orchestra Platform, discount the "seamless integration" claim — you are adding a dependency for something Debugbar already does better.

2. Register the provider manually. Laravel 5.4 predates package auto-discovery, so nothing happens until you edit config/app.php:

   'providers' => [
       // ...
       Orchestra\Debug\DebugServiceProvider::class,
   ],
   

   Add the facade alias to aliases in the same file if the package ships one.

3. Publish the config and read it as documentation. The published stub is the fastest map of what the profiler actually exposes — query logging switch, timeline thresholds, environment allowlist:

   php artisan vendor:publish --provider="Orchestra\Debug\DebugServiceProvider"
   

4. Confirm the environment gate is fail-closed. The description promises environment-aware toggling, but "configurable" is not "safe by default." Find the flag, verify local is on the allowlist and production is not, and check whether it keys off APP_DEBUG, APP_ENV, a dedicated config key, or all three. Test it before you trust it (see Gotchas).

5. First use case: profile one slow page. Open the suspect URL locally, read the timeline to see which phase is eating time (bootstrap, controller, view, response), then cross-reference the query log for that phase only against the queries you expected to run. That one pass is roughly 80% of the package's value.

6. Where to look first in the codebase when the docs are thin (they will be): the service provider's register() and boot() methods, the published config stub, and any middleware it pushes onto the stack. Those three places answer every question the README won't. Also check whether the package ships views/assets — if so, they need publishing too, and a missing asset publish looks identical to "the panel is broken."

Implementation Patterns

Wrap every entry point in your own environment check. Do not let the package's toggle be your only defense — a misconfigured staging .env should not be able to render SQL bindings and env values to a user:

if (app()->environment('local')) {
    // enable panel / trigger profiling run
}

Timeline first, query log second. The query log is noise; the timeline tells you where to read. Run the request once, identify the hot phase, then narrow into queries for that phase only. Reading a 200-query log top to bottom is how people burn an afternoon and learn nothing.

Profile artisan commands and queue workers, not just HTTP. Long-running import/export and backfill jobs are where the interesting N+1s and binding surprises live, and they're the hardest to inspect with a browser-based profiler. If there's a command-level hook, use it:

public function handle()
{
    $start = microtime(true);

    // ... work ...

    if (app()->environment('local')) {
        $this->line(sprintf('elapsed: %.2fs, peak: %.1fMB', microtime(true) - $start, memory_get_peak_usage(true) / 1024 / 1024));
    }
}

Even if the package's own helpers don't cover CLI, its execution timers and memory tracking give you the shape of the check.

Use it for exception context during local repros. If the package exposes error-reporting helpers, that context (request state, environment, recent queries) at the moment of a throw is frequently faster than reconstructing the failure from storage/logs/laravel.log.

Wrap it in a thin adapter. You will almost certainly replace this at the next Laravel upgrade. Put the package behind one small class:

final class DevProfiler
{
    public function start(string $label): void { /* delegate */ }
    public function mark(string $label): void  { /* delegate */ }
    public function log(array $context): void  { /* delegate */ }
}

Swapping in Debugbar, Clockwork, or Telescope later becomes a one-file change instead of a grep across the codebase.

Standardize on exactly one profiler per app. A second profiler registering query listeners double-collects and distorts exactly the timings you're trying to read. Pick one, then remove the other from composer.json and the provider list — not just "don't enable it locally," because someone eventually will.

Absent from production builds, not merely disabled. The stronger guarantee is composer install --no-dev in release artifacts so the package is physically not shipped. Pair it with a CI assertion that the package is absent from production dependencies and that the toggle is false in staging/production config. Two independent checks beat one config flag.

Keep it off by default in CI. Query logging and timeline collection add measurable overhead to large test suites. Enable on demand for investigative runs.

Gotchas and Tips

Auto-discovery does not exist here. Class not found or "target is not instantiable" on boot almost always means the provider isn't registered in config/app.php. This is the single most common setup failure on 5.4, and it presents as a broken package rather than a config miss.

Test the environment gate explicitly — it's the only failure with real business consequence. A misfire renders SQL bindings, config values, and environment context to anyone who loads the page. Do this on install and after every config change:

APP_ENV=production php artisan serve   # hit a page, confirm no panel
APP_ENV=staging    php artisan serve   # repeat

Check whether the environment panel exposes secrets. If it lists env values, credentials, or connection strings, that panel is one toggle bug away from a disclosure. Either confirm it redacts, or exclude staging from the allowlist and use local only.

Run it alone the first time. Ask directly: does it conflict with, duplicate, or suppress barryvdh/laravel-debugbar or any existing query listener? If it registers its own middleware or DB listener alongside Debugbar, your timings are wrong and your query counts are doubled — worse than no profiler, because it produces confidently wrong performance data. Benchmark startup time, memory, and query fidelity against Xdebug on a representative page before making it the team standard.

Published config drifts from upstream stubs. Once you publish config/debug.php, that file is yours and it diverges silently on every future release. Put the package version in a comment at the top of the published config, and diff it against the stub when you bump the version.

Pin the version; don't hand-edit constraints. If ^3.4 won't resolve:

composer why-not orchestra/debug ^3.4

That names the blocking transitive dependency — usually the real answer to "can we upgrade yet?"

Extension points are thin — plan accordingly. The realistic surface is the service provider (bind your own implementations) and the published config. There is no plugin architecture; custom panels and collectors mean writing against Debugbar's or Clockwork's API, not this package's.

Debugging the profiler itself. If panels don't render but the package is installed and registered, check in this order: (1) provider registration, (2) config published, (3) environment allowlist, (4) asset/view publishing, (5) whether another profiler's middleware is short-circuiting the response pipeline.

Zero dependents and zero stars means you are the QA team. No community bug reports means regressions surface in your environment first, with no upstream pressure to fix them. If this becomes load-bearing for daily debugging, vendor a fork rather than waiting on a fix.

Record an expiry date on adoption. Write down "revisit when the Laravel upgrade lands" and assign an owner. The realistic expected outcome at the next upgrade milestone is removal, not replacement — plan the rip-out while the integration is still small, not in the middle of the upgrade.