Laradumps Core Laravel Package

Getting Started

This is the engine, not the whole product. laradumps-core contains the dumper classes, the socket client that ships payloads to the desktop app, and the ds() / dsd() helpers. If you are on Laravel you almost certainly want the adapter (laradumps/laradumps), which depends on this package and adds query/log/model listeners and the Blade directive. Install core directly only for framework-agnostic PHP (plain scripts, CLI tools, other frameworks).

Minimal path:

1. Install and open the LaraDumps desktop app first. Without it running, nothing is rendered — the package fails silently by design.
2. composer require --dev laradumps/laradumps (Laravel) or composer require --dev laradumps/laradumps-core (everything else).
3. If you need to change host/port or disable it, publish the config: php artisan vendor:publish --tag=laradumps-config. Defaults are 127.0.0.1:9191.
4. Drop ds('hello') into a controller and reload the page. The payload appears in the app window, and the HTTP response completes normally.

Look here first, in this order:

• config/laradumps.php — host, port, and the enable/disable switch. This is where 90% of "it doesn't work" issues are resolved.
• src/LaraDumps.php — the fluent API surface. Read the public methods; that is the real documentation for what ds()->... can do.
• src/helpers.php — the exact signatures of ds() and dsd(), and whether the helper auto-instantiates or resolves from a container.
• The desktop app's own screen/clear controls — they determine what you actually see.

First real use case: replacing dd() and dump() inside a controller or Livewire component so you can inspect a value without killing the response or dirtying the HTML output.

Implementation Patterns

Chain modifiers off a dump instead of dumping raw. The fluent API is the whole point:

ds($user)->label('Authenticated user')->color('blue');
ds($order->items)->label('Items')->color('orange');

label() and color() are what keep a busy screen readable when you have eight dumps from one request.

Use dsd() deliberately. dsd($payload) dumps and dies. It is the right tool for "the request is already broken, show me state and stop", and the wrong tool inside loops or queued jobs.

Separate concurrent work with screens. When you are debugging two features at once, ds()->screen('checkout') and ds()->screen('auth') keep the streams apart instead of interleaving. Clear a screen at the top of a request (ds()->clear()) when you want a clean slate per hit.

Gate on isEnabled() for anything expensive. Building a large array purely to dump it is wasted work in production or when the app is closed:

if (ds()->isEnabled()) {
    ds($collection->map(fn ($i) => $i->only(['id', 'status']))->all());
}

Note the projection — send a trimmed shape, not the hydrated models.

Use the domain-specific dumpers rather than print_r-ing everything. In the Laravel adapter you get ds()->model($user), ds()->queries(), ds()->table($rows), ds()->diff($before, $after), and log capture. Reach for table() for arrays of uniform rows and diff() for before/after state — they are far more legible than a raw var-dump.

Framework-agnostic bootstrap. Outside Laravel, instantiate the dumper yourself and keep a single instance around per process. In long-running CLI tools this avoids re-instantiating the socket client on every call. This is the primary reason to depend on core directly.

Where to call it day-to-day:

• Tinker / php artisan tinker — inspect models and relationships without dd() ending the session.
• Artisan commands and jobs — payloads still reach the app; the job's output stream is unaffected.
• Blade — the adapter's directive lets you dump a view variable in place.
• Tests — leave it installed but disabled; see Gotchas.

Integration tip: wrap, don't scatter. If a team uses this heavily, add a tiny helper or macro for the shapes you dump repeatedly (e.g. dsq($query) that dumps SQL plus bindings plus execution time). It keeps call sites short and makes it trivial to grep for every debug call before a release.

Gotchas and Tips

• Silent failure is the default. If the desktop app is not running, or the port is wrong, the dump simply does not appear. There is no exception and no log line. Before debugging your code, confirm the app is open and the port matches.
• Docker / Sail / VMs break 127.0.0.1. Inside a container, loopback is the container, not your host. Set host to host.docker.internal (Docker Desktop) or the host gateway IP, and make sure the port is reachable. This is the single most common setup failure.
• Do not assign the return value. ds($user) returns the dumper object for chaining, not $user. $user = ds($user) will silently change the type of your variable and produce a confusing downstream bug.
• config:cache freezes your settings. If you toggle enabled or change the port in .env and nothing changes, you are looking at a cached config. Re-run php artisan config:cache or clear it.
• Never leave it enabled in production. It writes debug payloads to a local socket and can leak model data, credentials in query bindings, and request state. Gate on environment and prefer --dev in composer.json. ds() calls that ship to prod are a liability even when the app is closed.
• Huge payloads hurt. Dumping an entire Eloquent collection with relations, or a multi-megabyte response body, will stall the desktop app and make it look like your code hung. Slice, ->take(), or project before dumping.
• dsd() in a loop kills the request on the first iteration. If you need per-iteration output, use ds() with a label carrying the index.
• Version skew between the desktop app and the core package can break rendering. The payload schema evolves. If dumps render blank or malformed after an upgrade, align the app and package versions before assuming a bug in your code.
• ds()->queries(), log capture, and the Blade directive live in the Laravel adapter, not in core. Installing only laradumps-core and wondering where the query panel is a common confusion.
• Disable in the test suite. Socket writes add latency and nondeterminism to CI. Set the enabled flag off in phpunit.xml rather than deleting calls, so local debugging still works.
• Extension point: because this is the core, the clean way to add behaviour (custom payload shapes, extra context like request ID or user) is a small wrapper around the dumper rather than patching vendor files — your wrapper survives composer update, and the fluent chain stays intact.