Debug Bundle Laravel Package

Getting Started

symfony/debug-bundle is a Symfony full-stack bundle, not a Laravel package. There is no config/bundles.php, no Bundle::boot(), and no DI extension tree in Laravel, so requiring it in composer.json gets you classes that will never be wired. The honest day-to-day lever is the two things it bundles: symfony/var-dumper (which Laravel already ships with dump()/dd()/@dump) and MonologBridge's ServerLogCommand (which Laravel's laravel/pail already replaces). Treat the package as documentation for how Symfony wires those components, and replicate the wiring yourself.

Minimal steps:

# already transitive in every Laravel app
composer show symfony/var-dumper

# log tailing — the Laravel-native equivalent of server:log
composer require --dev laravel/pail

# the dump server listener shipped by var-dumper
vendor/bin/var-dump-server

First use case: run vendor/bin/var-dump-server in one terminal, register a ServerDumper handler in a dev-only service provider (see below), then dump($order->toArray()) from Tinker, a controller, or a queued job and watch dumps land in the listener terminal instead of corrupting an HTTP/JSON response.

Look first at: Illuminate\Support\Traits\Dumpable (->dump() / ->dd() on queries, collections, requests, responses), the @dump() Blade directive, and php artisan pail. Those cover ~90% of what debug-bundle gives a Symfony dev.

Implementation Patterns

Baseline inline debugging. Prefer the chainable helpers over global functions — they read better inside pipelines and return $this:

User::where('active', true)->dump()->limit(5)->get();
$request->dump();
collect($payload)->dd();

Use dump() (non-fatal, multi-arg) over dd() anywhere the process must survive: queue workers, finally blocks, DB transactions, Octane.

Dump server wiring (the DebugBundle autowiring, done by hand). debug.dump_destination: tcp://... is Symfony config that Laravel cannot read. Register the handler yourself:

// app/Providers/DumpServerServiceProvider.php
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
use Symfony\Component\VarDumper\Dumper\ServerDumper;
use Symfony\Component\VarDumper\VarDumper;

public function register(): void
{
    if (! $this->app->environment('local')) {
        return;
    }

    $cloner = new VarCloner();
    $cloner->setMaxItems(150);
    $cloner->setMaxString(2_000);

    $dumper = new ServerDumper('tcp://127.0.0.1:9912', new CliDumper());

    VarDumper::setHandler(static fn ($value) => $dumper->dump($cloner->cloneVar($value)));
}

Register it after Laravel's own providers so it wins. Because dd() in symfony/var-dumper routes through VarDumper::dump() then exits, the custom handler applies to dd() too — dumps go to the listener instead of the browser.

Cloner limits as a first-class setting. Doctrine entities and Eloquent models blow up the cloner. setMaxItems() / setMaxString() above are the Laravel equivalent of the Symfony var_dumper.cloner service arguments. Tune once, in one place, rather than sprinkling ->toArray() everywhere.

Capturing dumps for later inspection (the profiler/toolbar role). DebugBundle's real magic is DumpDataCollector collecting dumps into the web debug toolbar. The nearest Laravel pattern is a handler that pushes Data objects into a singleton buffer, then a middleware that logs them per-request:

VarDumper::setHandler(function ($v) use ($cloner) {
    app(DumpBuffer::class)->push($cloner->cloneVar($v)); // render into Telescope or a log channel
});

Keep this opt-in behind an env flag; it allocates memory on every dump.

Log tailing. Use php artisan pail --filter=error for the normal case. Only reach for MonologBridge if you specifically want the Symfony server:log UX (structured multi-line records over a socket, --host for containers): add Symfony\Bridge\Monolog\Handler\ServerLogHandler as a handler on the channel you want to tail, then wrap Symfony\Bridge\Monolog\Command\ServerLogCommand in an Artisan command. That wrapper is yours to maintain — weigh it against Pail first.

Environment and CI gating. Gate on app()->environment(['local', 'testing']) and config('app.debug'). Add a CI grep or a PHPStan disallowed-calls rule for \bdump\(|\bdd\(|\bddd\(|@dump so debug calls cannot merge. APP_DEBUG=false does not suppress dump().

Gotchas and Tips

• The bundle itself will silently no-op. composer require symfony/debug-bundle succeeds (its transitive deps often already satisfy Laravel's), but nothing registers. No toolbar, no dump_destination, no server:log. Don't diagnose "why isn't my dump server picking up" as a config problem — it's an architectural one.
• Version skew. Symfony 8 requires PHP ≥ 8.4; Laravel's pinned symfony/var-dumper is usually a major behind. Requiring the bundle can force-upgrade symfony/http-foundation / symfony/console out from under Laravel. If you need VarDumper features, require symfony/var-dumper explicitly with Laravel's constraint, never the bundle.
• VAR_DUMPER_FORMAT / VAR_DUMPER_SERVER env vars. Newer VarDumper releases read these in dump() to route to a server without any provider code. Verify against your pinned version — behaviour changed across majors — and fall back to the explicit VarDumper::setHandler() wiring, which is deterministic.
• Containers and Sail/Laradock. The dump server binds 127.0.0.1 by default. Start it with --host=0.0.0.0 and publish port 9912, or the app container's dumps hit the CliDumper fallback and land in the web server log where you'll never find them.
• Dumps break JSON clients and streamed responses. Any dump() inside an API response body corrupts the payload for the consumer. Use the server handler in any route that serves machines, not humans.
• dd() kills workers and requests mid-transaction. In a queue worker it terminates the process (Supervisor restarts it, job silently redelivered). In a DB::transaction it leaves an open transaction until timeout. Use dump() there.
• Huge payloads. Dumping a whole Collection of Eloquent models triggers lazy-loads and can dump relation graphs recursively. Prefer dump($q->toSql(), $q->getBindings()) for queries, and set Model::preventLazyLoading() so N+1s surface as exceptions rather than as a wall of dump output.
• Xdebug interference. xdebug.overload_var_dump and xdebug.var_display_max_depth mangle VarDumper output. Set xdebug.overload_var_dump=0 and let VarDumper own dump().
• Extension points worth knowing. ServerDumper accepts context providers (add request ID / user ID / job class to every dump — signature varies by version, check the constructor). Custom DumperInterface implementations let you push dumps to Slack, a file per request, or Ray. DumpDataCollector is the reference implementation for anything "collect dumps for later".
• Blade @dump is inside the view. View caching won't hide it, and php artisan view:cache will happily compile your leftover debug directive into production. The CI grep catches this; nothing else will.