The VarDumper Component

Installation

1

$ composer require --dev symfony/var-dumper

The dump() Function

The VarDumper component creates a global dump() function that you can use instead of e.g. var_dump. By using it, you'll gain:

• Per object and resource types specialized view to e.g. filter out Doctrine internals while dumping a single proxy entity, or get more insight on opened files with stream_get_meta_data;
• Configurable output formats: HTML or colored command line output;
• Ability to dump internal references, either soft ones (objects or resources) or hard ones (=& on arrays or objects properties). Repeated occurrences of the same object/array/resource won't appear again and again anymore. Moreover, you'll be able to inspect the reference structure of your data;
• Ability to operate in the context of an output buffering handler.

For example:

1
2
3
4
5
6
7
8
9

require __DIR__.'/vendor/autoload.php';

// create a variable, which could be anything!
$someVar = ...;

dump($someVar);

// dump() returns the passed value, so you can dump an object and keep using it
dump($someObject)->someMethod();

By default, the output format and destination are selected based on your current PHP SAPI:

• On the command line (CLI SAPI), the output is written on STDOUT. This can be surprising to some because this bypasses PHP's output buffering mechanism;
• On other SAPIs, dumps are written as HTML in the regular output.

The Dump Server

The dump() function outputs its contents in the same browser window or console terminal as your own application. Sometimes mixing the real output with the debug output can be confusing. That's why this component provides a server to collect all the dumped data.

Start the server with the server:dump command and whenever you call dump(), the dumped data won't be displayed in the output but sent to that server, which outputs it to its own console or to an HTML file:

1
2
3
4
5
6

# displays the dumped data in the console:
$ php bin/console server:dump
  [OK] Server listening on tcp://0.0.0.0:9912

# stores the dumped data in a file using the HTML format:
$ php bin/console server:dump --format=html > dump.html

Inside a Symfony application, the output of the dump server is configured with the dump_destination option of the debug package:

1
2
3

# config/packages/debug.yaml
debug:
   dump_destination: "tcp://%env(VAR_DUMPER_SERVER)%"

1
2
3
4
5
6
7
8

// config/packages/debug.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'debug' => [
        'dump_destination' => 'tcp://%env(VAR_DUMPER_SERVER)%',
    ],
]);

Outside a Symfony application, use the ServerDumper class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

require __DIR__.'/vendor/autoload.php';

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
use Symfony\Component\VarDumper\Dumper\ContextProvider\CliContextProvider;
use Symfony\Component\VarDumper\Dumper\ContextProvider\SourceContextProvider;
use Symfony\Component\VarDumper\Dumper\HtmlDumper;
use Symfony\Component\VarDumper\Dumper\ServerDumper;
use Symfony\Component\VarDumper\VarDumper;

$cloner = new VarCloner();
$fallbackDumper = \in_array(\PHP_SAPI, ['cli', 'phpdbg']) ? new CliDumper() : new HtmlDumper();
$dumper = new ServerDumper('tcp://127.0.0.1:9912', $fallbackDumper, [
    'cli' => new CliContextProvider(),
    'source' => new SourceContextProvider(),
]);

VarDumper::setHandler(function (mixed $var) use ($cloner, $dumper): ?string {
    return $dumper->dump($cloner->cloneVar($var));
});

Then you can use the following command to start a server out-of-the-box:

1
2

$ ./vendor/bin/var-dump-server
  [OK] Server listening on tcp://127.0.0.1:9912

1

$ ./vendor/bin/var-dump-server

1

$ VAR_DUMPER_FORMAT=server [your-cli-command]

DebugBundle and Twig Integration

The DebugBundle allows greater integration of this component into Symfony applications.

Since generating (even debug) output in the controller or in the model of your application may just break it by e.g. sending HTTP headers or corrupting your view, the bundle configures the dump() function so that variables are dumped in the web debug toolbar.

But if the toolbar cannot be displayed because you e.g. called die()/exit()/dd() or a fatal error occurred, then dumps are written on the regular output.

In a Twig template, two constructs are available for dumping a variable. Choosing between both is mostly a matter of personal taste, still:

• {% dump foo.bar %} is the way to go when the original template output shall not be modified: variables are not dumped inline, but in the web debug toolbar;
• on the contrary, {{ dump(foo.bar) }} dumps inline and may or not be suited to your use case (e.g. you shouldn't use it in an HTML attribute or a
  This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
  TOC

  Search

  Version