Laravel Debugger Laravel Package

Getting Started

Install as a dev-only dependency. Never in require:

composer require --dev akira/laravel-debugger

The package targets Laravel 12+ on PHP 8.4, so before you run anything, confirm your composer.json platform constraints. If your app or CI matrix still runs PHP 8.2/8.3, Composer will either refuse to install or silently resolve nothing — check composer why-not akira/laravel-debugger first rather than guessing.

Where to look first, in this order:

1. vendor/akira/laravel-debugger/README.md — with 4 stars and 0 dependents there is no community corpus to learn from; the README and the source are the documentation.
2. vendor/akira/laravel-debugger/config/*.php — if a config file exists, publish it (php artisan vendor:publish --provider="Akira\Debugger\DebuggerServiceProvider" --tag=config) and read every key. This tells you the real feature surface faster than prose.
3. The service provider's register()/boot() — look for the environment guard (e.g. $this->app->environment('local') or a enabled config flag). That single check determines whether you can safely leave it installed.

First use case: pick the narrowest, highest-pain thing you debug every week — usually a slow endpoint or a query N+1 — and instrument just that route. Register the package's middleware (or call its dump helper) on a single route rather than globally:

Route::get('/orders/{order}', OrderController::class)
    ->middleware('debugger'); // name per the package's registered alias

Confirm output appears locally and does not appear when APP_ENV=production and APP_DEBUG=false before you widen the scope.

Implementation Patterns

Route-scoped instrumentation over global middleware. Attach the debugger to a route group you're actively working on. Global registration on a package with zero dependents means one bad boot() method takes down every request in your app, with no community reports to warn you.

Route::middleware(['web', 'debugger'])->group(function () {
    Route::get('/checkout', CheckoutController::class);
});

Environment-gated config. Publish the config and drive it from .env so the flag is explicit and reviewable in a diff:

// config/debugger.php
'enabled' => env('DEBUGGER_ENABLED', false),

Then in .env.local only: DEBUGGER_ENABLED=true. This is safer than trusting the package's own default, which you haven't audited yet.

Wrap a suspected block, not the whole request. Use the package's timer/dump calls around the code you suspect, so the signal-to-noise ratio stays high:

debugger()->mark('before-payment');
$result = $this->gateway->charge($order);
debugger()->mark('after-payment')->dump($result);

(Exact API — mark, dump, timer, or a facade — must be read from the README; the pattern of bracketing a suspected call is what matters.)

Pair with a real profiler rather than replacing it. If the package leans on PHP 8.4 features for reflection or attribute-based instrumentation, it complements Telescope/Clockwork/Xdebug but doesn't replace them. Use this for "what is this value right now," use Xdebug for "where did 400ms go."

Keep it out of the test suite's hot path. Don't enable it in phpunit.xml globally; if you need assertions on debug output, enable per-test with config(['debugger.enabled' => true]) and reset in tearDown.

CI guard. Add a cheap check so a stray enable can't ship:

composer show akira/laravel-debugger --direct 2>/dev/null && grep -q "DEBUGGER_ENABLED=true" .env.example && exit 1

Even simpler: assert .env.example contains DEBUGGER_ENABLED=false.

Gotchas and Tips

The PHP 8.4 floor is the biggest real constraint. A debugging tool you can't install on your legacy service, your CI image, or a colleague's machine is a tool the team won't standardize on. Verify the floor in composer.json ("php": "^8.4") before proposing it in a team RFC — an unadopted dev tool is pure overhead.

Zero dependents means you are the QA team. No Stack Overflow answers, no GitHub issues corpus, no downstream packages pinning versions. Budget an hour to read the source before putting it in a real project, and expect to debug the debugger at least once. This is the main reason to prefer an established alternative unless the package solves something specific for you.

Single-maintainer risk / release date. The only release is dated 2026-02-24. Pin it exactly ("akira/laravel-debugger": "1.0.0" or whatever the tag is) rather than using a caret range, and treat a composer update that bumps it as a code review event.

Config caching will bite you. php artisan config:cache freezes DEBUGGER_ENABLED at its cached value. If you toggle it in .env and nothing changes, run php artisan config:clear — this is the #1 "the package is broken" false alarm for config-driven debug tools.

Debug output leaking to non-HTML responses. Packages that dump to the response body (rather than a log or a separate channel) can corrupt JSON APIs, file downloads, and streamed responses. Test against an Accept: application/json request and a binary download before enabling broadly.

Watch for double-registration. If the package auto-discovers (Laravel's package discovery), adding its service provider manually to config/app.php will register it twice — duplicated middleware, duplicated dumps. Check bootstrap/cache/packages.php after install to see what was auto-discovered.

Deployment hygiene. With require-dev, composer install --no-dev on production excludes it — but confirm your deploy pipeline actually uses --no-dev. Laravel Cloud/Forge/Vapor defaults vary. If your pipeline runs composer install without the flag, the package ships to production, and any unguarded boot() code runs there.

Extension points to check for, in priority order: (1) a debugger config with an enabled flag, (2) a middleware alias you can scope per-route, (3) a facade or debugger() helper for manual calls, (4) a driver/channel abstraction letting you send output to a log file instead of the response body. If (4) is missing, that's the first thing to wrap yourself — a small class that writes to storage/logs/debugger.log keeps output out of HTTP responses entirely.

Evaluate the alternatives honestly. For most teams, Telescope (first-party, huge community), Ray (paid, excellent DX), or Clockwork already cover this ground. Adopt akira/laravel-debugger only if its PHP 8.4-specific features — attributes, property hooks, asymmetric visibility in the dump output — give you something the incumbents don't. Otherwise you're trading ecosystem support for novelty.