Laravel Debugmate Laravel Package

Getting Started

irabbi360/laravel-debugmate is a Laravel debugging helper currently in beta (v1.0.0-beta.5). The headline change in this release is Laravel 10 support, so the package is now viable on L10 projects alongside the earlier 8/9 targets.

Minimal steps:

1. Install into a local/dev environment only:

   composer require irabbi360/laravel-debugmate:^1.0.0-beta.5
   

2. The package's service provider is auto-discovered. If you need to tweak behaviour, publish the config:

   php artisan vendor:publish --provider="Irabbixx\Debugmate\DebugmateServiceProvider"
   

3. Guard it by environment. Never let a debug package run in production — wrap any enable flag in config('app.debug') or an explicit DEBUGMATE_ENABLED env var, and confirm the package's own config does the same before you deploy anywhere shared.
4. First use case: drop it into a fresh feature branch when a request is behaving unexpectedly — inspect what the framework is doing (queries, request lifecycle, resolved bindings) without reaching for dd() and killing the response.

Before writing code against it, read two things in the repo: the README (for the current public API surface) and src/ for the service provider and config file. At beta.5 the API is not yet frozen, so the source is the source of truth.

Implementation Patterns

Local-only debugging. Treat the package as a developer-experience tool, not application infrastructure. The cleanest pattern is to require it with --dev semantics in your head even though Composer may not split it: keep it out of the production composer install --no-dev path, or gate every call site behind app()->isLocal().

if (app()->isLocal()) {
    // invoke debugmate helpers here
}

Throwaway instrumentation. The highest-value workflow is transient: add a call, inspect output, remove the call. Resist wrapping application code in debug calls permanently — they become noise and a performance tax once someone forgets one.

Pairing with Telescope/Debugbar. Debugmate is not a replacement for Laravel Telescope. Use it for quick, in-request inspection when you don't want a full dashboard; keep Telescope for historical/post-hoc tracing. They coexist fine because both are dev-only.

Testing integration. Add a smoke test that resolves the package's service provider so a Laravel 10 upgrade or a Composer bump doesn't silently break bootstrapping:

public function test_debugmate_provider_boots(): void
{
    $this->assertTrue(app()->providerIsLoaded(
        \Irabbixx\Debugmate\DebugmateServiceProvider::class
    ));
}

CI guard. Add a check that the package never appears in your production lockfile diff, or assert DEBUGMATE_ENABLED=false in staging config so a mis-set env doesn't expose diagnostics.

Gotchas and Tips

• Beta API churn. 1.0.0-beta.5 is pre-stable. Class names, config keys, and helper signatures can change between betas without deprecation notices. Pin the exact beta ("1.0.0-beta.5") rather than using ^1.0.0-beta, and re-read CHANGELOG/diff on every bump.
• Laravel 10 is new here. This release adds L10 support, which means it is the least-tested combination. If you're on L10, exercise the package's main paths manually once before relying on it — particularly anything touching the container, middleware, or the query/event listeners, where L10's changes (PHP 8.1 minimum, updated type handling) tend to surface breakage.
• Environment leakage is the real risk. Debug tooling that renders output or exposes internals can leak stack traces, SQL, or config into HTTP responses. Verify the enable flag defaults to false and that APP_DEBUG=false in every non-local environment.
• Config caching quirk. If you publish the config, remember php artisan config:cache will freeze it. After changing debugmate settings locally, run php artisan config:clear or you'll debug a stale configuration.
• Debugging the debugger. If output doesn't appear, check in this order: (1) is the provider loaded (php artisan about), (2) is the enable flag actually true in the current env, (3) is config cached, (4) does the request path actually hit the code you instrumented. Nine times out of ten it's (2) or (3).
• Extension points. The published config and the service provider's bindings are your only stable-ish levers at beta. If you need custom behaviour, prefer binding a decorator in your own AppServiceProvider over editing vendor files — composer update will erase the latter.
• Performance. Any listener-based instrumentation adds overhead per request. Keep it disabled outside local; don't benchmark a dev machine with it on and draw conclusions about production throughput.