Inspector Laravel Package

Getting Started

Install

composer require lsrur/inspector --dev

Register the service provider (Laravel <5.5 only)

// config/app.php
'providers' => [
    Lsrur\Inspector\InspectorServiceProvider::class,
],
'aliases' => [
    'Inspector' => Lsrur\Inspector\Facades\Inspector::class,
],

Publish the config

php artisan vendor:publish --provider="Lsrur\Inspector\InspectorServiceProvider"

This drops config/inspector.php — the first place to look when behavior feels surprising (see Gotchas).

Wire up the middleware in app/Http/Kernel.php. For a typical web app:

protected $middlewareGroups = [
    'web' => [
        // ...
        \Lsrur\Inspector\Middleware\WebInspectorMiddleware::class,
    ],
];

Use the plain InspectorMiddleware for API/JSON routes, and WebInspectorMiddleware for HTML-rendering routes — the "web" variant injects a floating panel, the plain one only emits console/log data.

First use case — replace dd() and var_dump() with something non-fatal:

use Inspector;

public function index()
{
    Inspector::log('entering index');
    Inspector::info($request->all());
    Inspector::error('something odd happened');

    $users = User::all();
    Inspector::dump($users);   // pretty-print without halting

    return view('home');
}

Trigger a request; in a browser you get the floating panel; for AJAX/XHR you get a console.log payload readable in DevTools.

Implementation Patterns

Severity-level logging. Keep the same mental model as a standard logger:

Inspector::log('debug detail');
Inspector::info($payload);
Inspector::success('order created');
Inspector::warning('cache miss');
Inspector::error('failed to charge', ['order_id' => $id]);

Each accepts a message and optional context array — use context rather than string concatenation so the panel renders structured data.

Non-destructive variable inspection. dump() and logVars() are your dd() replacement that never stops execution. Wrap them in a helper if you find yourself reaching for them often:

if (config('app.debug')) {
    Inspector::logVars($order->toArray(), 'order');
}

Timers for profiling hot paths. The pattern is start/stop around the suspected block, not around the whole request (the middleware already measures totals):

Inspector::startTimer('elastic-search');
$results = $search->run($query);
Inspector::stopTimer('elastic-search');

Inspector::startTimer('render');
return view('results', compact('results'));
Inspector::stopTimer('render');

Checkpoints / memos. Inspector::memo('after-import') (or add() in some versions) lets you annotate the timeline so the panel's chronological view is readable when many things fire.

Route-scoped debugging. Don't flood every request. Register the middleware on specific routes only:

Route::middleware(['web', \Lsrur\Inspector\Middleware\WebInspectorMiddleware::class])
    ->group(function () {
        Route::get('/debug/orders', 'DebugController@orders');
    });

Custom exception reporting. Feed caught exceptions into the panel instead of ignoring them:

try {
    $client->send($payload);
} catch (\Exception $e) {
    Inspector::exception($e);
    // handle...
}

This is the day-to-day win: an exception caught and swallowed deep in a job shows up in the panel with trace, rather than vanishing.

Correlating AJAX. For fetch/Axios calls, the plain InspectorMiddleware is the right choice — every response carries the console payload, so multiple XHR calls each log independently in the browser console. Add a request ID via Inspector::info($request->header('X-Request-Id')) at the top of the controller if you need to interleave them.

Event/query/views toggles. The config file gates what the middleware collects. Turn off what you don't need per environment — e.g. on a slow staging box, keep queries and timers but drop views and traces to reduce overhead.

Gotchas and Tips

Debug-only by design — but verify. The shipped config defaults enable to APP_DEBUG. That is not a production safety guarantee: if APP_DEBUG=true slips into prod, the panel injects into HTML and may leak stack traces. Belt-and-braces: add an explicit env('INSPECTOR_ENABLE', false) and never depend on APP_DEBUG alone. Keep the package in require-dev.

HTML injection corrupts binary/streamed responses. WebInspectorMiddleware appends markup to the response body. This breaks downloads, PDFs, streams, and anything where a trailing <script> matters. Use the plain InspectorMiddleware for those routes, or disable inject in config and rely on the console output only.

AJAX + wrong middleware = broken JSON. If the web middleware injects into a JSON response, clients choke. Match middleware to response type — this is the most common support question.

Facade resolves even when disabled — but silently no-ops. Inspector::log() in production without the package enabled will not throw, but you may have added real overhead (context arrays built eagerly, etc.). Guard expensive context building:

if (Inspector::isEnabled()) {
    Inspector::info($heavy->serialize());
}

(or gate behind config('app.debug')); otherwise your "zero-cost in prod" assumption is wrong.

Middleware order matters. Place the inspector middleware after session/auth middleware so it sees the final response and the authenticated user, but before anything that itself inspects the response body. Misordering causes missing data or double injection.

Console vs. panel confusion. XHR-triggered requests go to the browser console, not the floating panel. If "nothing shows up" during an Axios call, open DevTools Console — you're probably looking at the wrong surface.

Traces are expensive. Enable trace only for a single debugging session. Full stack traces on every log entry will dominate request time and blow out the payload.

Timers must be balanced. A stopTimer() without a matching startTimer() (e.g., after an early return inside the timed block) leaves an open timer and confusing output. Wrap in try/finally when the block can throw or return early.

Config cache. Changes to config/inspector.php don't apply until php artisan config:clear if you've cached config. This is the #1 "my settings aren't taking effect" issue.

Extension points. Output templates live in the package's views — publish them (vendor:publish --tag=inspector-views if available, or copy from the package) to customize the panel's appearance/branding. To capture your own data streams, register listeners for the framework events the middleware hooks (queries, events) rather than monkey-patching the middleware; a Log::listen-style approach or a dedicated event subscriber keeps your additions upgrade-safe.

Not a production APM. This is a local dev aid. If you need per-request profiling in staging/prod, pair it with a real APM (Telescope, Clockwork, or a hosted service) rather than trying to enable Inspector outside local.