Laradump Laravel Package

Getting Started

thejenos/laradump is a self-hosted answer to spatie/ray: instead of dumping into the HTTP response (and corrupting JSON APIs, Blade output, or Livewire payloads), it ships the payload over a socket to a separate viewer app. Treat it as a dev-only convenience, not infrastructure.

Minimal setup:

composer require --dev thejenos/laradump
php artisan vendor:publish --provider="TheJenos\Laradump\LaradumpServiceProvider"

Then confirm the two things that matter in config/laradump.php:

// config/laradump.php (shape will vary slightly — read the published file)
'enabled' => env('LARADUMP_ENABLED', true),
'host'    => env('LARADUMP_HOST', '127.0.0.1'),
'port'    => env('LARADUMP_PORT', 9000),

Add LARADUMP_ENABLED=false to .env.production / .env.testing immediately, before you write a single debug call.

Where to look first: the package src/ is tiny — find helpers.php (or equivalent) for the global functions and the config file for the transport. Read those two before the README; you'll understand the whole package in five minutes. The second stop is your own phpunit.xml and .env.example, because the failure mode of this package is silence.

First use case: swap a dd() you're already doing today.

// before: destroys the request, breaks the JSON response
dd($order->toArray());

// after: request completes normally, payload appears in the viewer
ld($order->toArray());

The high-value moment is debugging something you cannot see in a response: a queued job, an Artisan command, a scheduled task, a Stripe webhook handler, or an Inertia/Livewire AJAX round-trip. That's where ld() beats Log::debug() (structured, inspectable arrays) and beats dd() (non-destructive).

Implementation Patterns

Chainable debugging. The helper returns its argument, so it slots into an existing expression without restructuring:

return ld($user->load('roles'))->only('id', 'email', 'roles');

Query inspection — the single most common daily use:

$q = Order::where('status', 'pending')->whereDate('created_at', $date);
ld($q->toSql(), $q->getBindings());

Queues and jobs. Worker processes have no response body, so dump() is useless there. ld() is the natural tool — but tag the output so you can tell which job/attempt produced it:

public function handle()
{
    ld(['job' => self::class, 'attempt' => $this->attempts(), 'order' => $this->order->id]);
    // ...
}

Exception visibility. Wire the viewer into app/Exceptions/Handler.php (or the Laravel 11 bootstrap/app.php withExceptions closure) so uncaught exceptions in jobs and webhooks land in the viewer instead of only in storage/logs:

public function report(Throwable $e)
{
    if (app()->environment('local')) {
        ld(['exception' => $e::class, 'message' => $e->getMessage()]);
    }
    parent::report($e);
}

Isolate it behind your own seam. This is the most important pattern given the package's status. Never scatter ld() across the codebase directly; give yourself one indirection:

// app/Support/Debug.php
public static function send(mixed ...$values): mixed
{
    if (app()->environment('local') && config('laradump.enabled')) {
        ld(...$values); // ← the only laradump call in the app
    }
    return $values[0] ?? null;
}

Swapping to Ray, Sentry breadcrumbs, or plain Log::debug() later is then a one-file change.

Debugging HTTP context you can't echo into. For API controllers, ld() keeps the JSON contract intact:

public function store(StoreOrderRequest $request)
{
    ld($request->validated());           // viewer only
    $order = Order::create($request->validated());
    return response()->json($order, 201); // client sees clean JSON
}

Testing hygiene. Put LARADUMP_ENABLED=false in phpunit.xml under <php>, not just .env.testing — CI often ignores the latter, and a stray ld() in a hot loop will hang or slow the suite when no viewer is listening.

Gotchas and Tips

The package is archived (last release Nov 2021, 21 stars, zero dependents). This is the headline risk. Assume no fixes for PHP 8.2+ deprecations, Laravel 10/11 service-provider changes, or readonly/typed-property edge cases in the dumper. Before adopting: run composer require on your actual PHP/Laravel version and check whether the constraint even resolves. If it doesn't, either fork it (it's MIT and ~small) or pin your expectations to "local dev toy" and keep the Debug::send() seam so removal is trivial.

Silent failure by design. If the viewer isn't running, the wrong port is configured, or a firewall blocks the socket, you get nothing — no exception, no log line. Symptom: "laradump is broken." Diagnosis order: (1) config('laradump.enabled'), (2) is the listener actually up (lsof -i :9000 / nc -z 127.0.0.1 9000), (3) host mismatch. Always check the config resolves to what you think with php artisan tinker --execute="dump(config('laradump'));".

Docker / Sail / Homestead break 127.0.0.1. Inside a container, localhost is the container. Use LARADUMP_HOST=host.docker.internal (macOS/Windows) or the host gateway IP on Linux. This is the number-one setup failure for any Ray-style tool.

Loops flood the socket. ld() inside ->each() or a 10k-row seeder will make the request crawl. Guard with an index check or dump aggregates (counts, take(5)->toArray()) rather than every row.

Never let ld() into a request that reaches production. Gate on app()->environment('local') and the config flag. Payloads commonly include user models, tokens in headers, and request bodies — a leaked LARADUMP_ENABLED=true in prod is a data-exfiltration path, not just noise.

Don't confuse it with dump(). If you call dump()/dd() by reflex, you're back to broken responses. Consider a code-review grep or a Pint/phpstan rule banning dd( in app/ so ld( becomes the house style.

Extension points are thin but real: the published config (host/port/enabled) and the service-provider binding are the levers. If you need custom serialization (large Eloquent graphs, circular relations), the clean approach is to pre-shape the payload yourself ($model->toArray() with $hidden trimmed) rather than fight the dumper.

Watch payload size. Deeply nested relations or $request->all() on a big form can produce megabytes over the socket and stall the viewer. Dump $model->only([...]) or ->toArray() of a specific subset.

Have an exit plan. Before the first commit, decide what replaces this: spatie/ray (maintained, paid app), Laravel Telescope (browser-based, maintained, better for team/CI visibility), or Log::channel('daily') with structured context. Ten minutes of planning now saves a forced migration later — which is exactly the tradeoff you're accepting by adopting a 2021 archived package for day-to-day debugging.