README

Send faithful, typed value dumps and structured debug messages (exceptions, SQL queries, HTTP calls, logs, models, …) to the Dumpio viewer. HTTP-first, fire-and-forget, never breaks the host app — every call swallows its own errors and silently drops if the viewer isn't running.

Built to the authoritative client contract in ../BUILDING.md. For a thorough, example-driven walkthrough see docs/GUIDE.md.

Install

composer require dumpio/client

Configuration is read from the environment, or override it at runtime:

use Dumpio\Dumpio;

Dumpio::configure(['host' => 'localhost', 'port' => 21234, 'token' => 'secret']);

The basics — var dumps

dio($user, 'user')->green();   // fluent builder (auto-sends); see below
dumpio($user, 'user', 'blue'); // tap-style: sends and returns $user, like tap()
ddio($a, $b);                  // dump every arg, then die
// or: Dumpio::dump($user, 'user'); Dumpio::dd($a, $b);

dio() returns the fluent builder so you can chain color/label/flood control; dumpio() returns the value so you can wrap an expression. Pick by need.

The var serializer uses Reflection, so member visibility (public/protected/private), class names, typed/uninitialized properties and enums are preserved. It breaks cycles via ref nodes and bounds depth/items/string length. The calling file:line is captured automatically.

It also recognises a few common shapes and renders their logical value instead of raw internals: DateTimeInterface becomes a formatted date, an Eloquent model becomes its casted/visible attributes (via attributesToArray()), and a Laravel Collection becomes its items. These checks are by class name, so the core stays framework-agnostic and they are inert when Laravel is absent.

Fluent builder & flood control

dio() (and Dumpio::make()) return a chainable builder. The dump ships on ->send() or automatically when the builder goes out of scope, so ->send() is optional:

dio($user)->red()->label('user')->channel('auth');   // auto-sends
Dumpio::make($payload)->purple()->send();             // explicit send

Colors: red() yellow() blue() gray() purple() pink() green() (or flag('…')), plus label(), channel(), and conditional when($bool) / unless($bool).

Helpers keep loops from flooding the viewer (keyed by call-site file:line, per process — or by an explicit name):

foreach ($rows as $row) {
    dio($row)->once();          // only the first iteration is sent
    dio($row)->limit(5);        // at most 5 are sent
    dio($row)->count();         // one live-updating entry, "×N" in the viewer
    dio($row)->count('rows');   // share one counter across call-sites
}

Time a block with a stopwatch (ships a measure dump with elapsed ms + memory):

$sw = Dumpio::stopwatch('import');
$sw->lap('parsed');   // intermediate split, keeps running
$sw->stop('done');    // final timing

Chainable macros (Laravel)

On Laravel, ->dio() and ->ddio() are registered as macros on query builders and collections, so you can drop a dump mid-chain without breaking it — it ships the current state and returns $this:

User::query()
    ->where('name', 'John')
    ->dio()                              // → query dump (SQL + bindings so far)
    ->whereDate('email_verified_at', '2024-02-15')
    ->dio()                              // → query dump (with the extra clause)
    ->first();

collect($users)->dio('after filter');    // → var dump, returns the collection

->ddio() is the dump-and-die variant. Works on Eloquent\Builder, Query\Builder (DB::table(...)) and Support\Collection. Disable with DUMPIO_REGISTER_MACROS=false.

Typed helpers

Every helper is a static method on Dumpio (fire-and-forget). $opts always accepts envelope overrides: flag, channel, origin.

html / mail render foreign markup in the viewer's sandboxed iframe (no scripts, remote resources blocked by default); mail adds a subject/from/to envelope. See the guide.

Flags are picked automatically where it helps: exceptions are red, queries purple, HTTP by status (≥500 red, ≥400 yellow, ≥300 blue, else green), logs by level (error red, warning yellow, info blue).

Two thin global wrappers are also autoloaded for the most common cases:

dumpio_exception($e, ['user' => ['id' => 1]]);
dumpio_query('select * from users', [], 1.2);

Laravel

The service provider is auto-discovered — no manual registration. It reads config('dumpio.*'), configures the static client, and (opt-in) forwards queries and exceptions.

Publish the config:

php artisan vendor:publish --tag=dumpio-config

config/dumpio.php:

return [
    'host' => env('DUMPIO_HOST', 'localhost'),
    'port' => (int) env('DUMPIO_PORT', 21234),
    'token' => env('DUMPIO_TOKEN', ''),
    'enabled' => env('DUMPIO_ENABLED', env('APP_DEBUG', false)), // off in prod
    'listen_queries' => env('DUMPIO_LISTEN_QUERIES', false),     // DB::listen → query dumps
    'listen_exceptions' => env('DUMPIO_LISTEN_EXCEPTIONS', false), // reported exceptions → exception dumps
    'intercept_dumps' => env('DUMPIO_INTERCEPT_DUMPS', false),   // dump()/dd() → the viewer
    'listen_models' => env('DUMPIO_LISTEN_MODELS', false),       // Eloquent created/updated/deleted/restored → model dumps
    'listen_cache' => env('DUMPIO_LISTEN_CACHE', false),         // cache hit/miss/written/forgotten → event dumps
    'listen_jobs' => env('DUMPIO_LISTEN_JOBS', false),           // queue job processing/processed/failed → event dumps
    'listen_events' => env('DUMPIO_LISTEN_EVENTS', false),       // application (non-framework) events → event dumps
    'listen_mail' => env('DUMPIO_LISTEN_MAIL', false),           // outgoing email → mail dumps (rendered preview)
    'intercept_mail' => env('DUMPIO_INTERCEPT_MAIL', false),     // + swallow the real send in dev (Mailpit-style)
    'listen_http_client' => env('DUMPIO_LISTEN_HTTP_CLIENT', false), // outgoing Http:: calls → http dumps
    'listen_livewire' => env('DUMPIO_LISTEN_LIVEWIRE', false),   // Livewire component lifecycle → event dumps
];

When enabled is false (the default in production) the provider configures the client as disabled and registers no listeners — a complete no-op.

Auto-instrumentation (opt-in)

Each switch below is off by default; flip the env var to forward that signal:

Runtime toggles

Config flags only seed the initial state. Any capture can be flipped on or off at runtime — handy inside a test, a Tinker session, or around a suspect block:

Dumpio::showQueries();          // start forwarding queries now
// … the code you want to inspect …
Dumpio::stopShowingQueries();   // and stop

Dumpio::showAll();              // everything on
Dumpio::stopShowingAll();       // everything off

Pairs exist for Queries, Exceptions, Dumps, Models, Cache, Jobs, Events, Mail, HttpClient and Livewire.

Logs → the viewer (Monolog)

Point a log channel at Dumpio\Log\DumpioHandler to stream app logs into the viewer as log dumps (level → flag colour):

// config/logging.php
'channels' => [
    'dumpio' => [
        'driver'  => 'monolog',
        'handler' => \Dumpio\Log\DumpioHandler::class,
    ],
],

Then Log::channel('dumpio')->warning('…'), or add 'dumpio' to a stack channel's channels list to mirror your default log.

Use the helpers anywhere, or the optional facade (also auto-discovered as the Dumpio alias):

use Dumpio\Laravel\Facades\Dumpio;

Dumpio::query($sql, $bindings, $timeMs);
// equivalently: \Dumpio\Dumpio::query(...) or dumpio_query(...)

Set DUMPIO_LISTEN_QUERIES=true to mirror every executed query into the viewer via DB::listen, and DUMPIO_LISTEN_EXCEPTIONS=true to forward reported exceptions through the framework's exception handler.

Symfony

Add the bundle (dev only is recommended):

// config/bundles.php
return [
    // …
    Dumpio\Symfony\DumpioBundle::class => ['dev' => true],
];

The bundle registers Dumpio\Symfony\EventSubscriber\ExceptionSubscriber, which forwards every kernel.exception to the viewer as an exception dump with the current request context. It reads DUMPIO_HOST / DUMPIO_PORT / DUMPIO_TOKEN / DUMPIO_DISABLE from the environment.

The bundle adds more auto-instrumentation when the relevant component is present:

The runtime toggles (Dumpio::showQueries() …) and the Monolog handler (Dumpio\Log\DumpioHandler) documented above work the same under Symfony.

Symfony cache pools have no built-in event system (unlike Laravel), so there is no automatic cache forwarding — call Dumpio::event('cache.…', …) yourself if you need it.

Symfony's MessageEvent has no cancel hook, so there is no intercept_mail here — the subscriber only captures mail. To keep dev mail from actually sending, point MAILER_DSN at a null://null transport.

You can also call the static client or helpers from anywhere in your code:

\Dumpio\Dumpio::query($sql, $bindings, $timeMs);
dumpio($entity, 'entity');

See ../BUILDING.md for the full wire contract and the shared var tree format.