The VarDumper Component

Installation¶

You can install the component in 2 different ways:

• Install it via Composer (symfony/var-dumper on Packagist);
• Use the official Git repository (https://github.com/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:

require __DIR__.'/vendor/autoload.php';
// create a variable, which could be anything!
$someVar = '...';

dump($someVar);

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.

DebugBundle and Twig Integration¶

The DebugBundle allows greater integration of the component into the Symfony full stack framework. It is enabled by default in the dev and test environment of the standard edition since version 2.6.

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 can not be displayed because you e.g. called die/exit 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 thus may or not be suited to your use case (e.g. you shouldn’t use it in an HTML attribute or a <script> tag).

By default for nested variables, dumps are limited to a subset of their original value. You can configure the limits in terms of:

• maximum number of items to dump,
• maximum string length before truncation.

Dump Examples and Output¶

For simple variables, reading the output should be straightforward. Here are some examples showing first a variable defined in PHP, then its dump representation:

$var = array(
    'a simple string' => "in an array of 5 elements",
    'a float' => 1.0,
    'an integer' => 1,
    'a boolean' => true,
    'an empty array' => array(),
);
dump($var);

$var = "This is a multi-line string.n";
$var .= "Hovering a string shows its length.n";
$var .= "The length of UTF-8 strings is counted in terms of UTF-8 characters.n";
$var .= "Non-UTF-8 strings length are counted in octet size.n";
$var .= "Because of this `xE9` octet (xE9),n";
$var .= "this string is not UTF-8 valid, thus the `b` prefix.n";
dump($var);

class PropertyExample
{
    public $publicProperty = 'The `+` prefix denotes public properties,';
    protected $protectedProperty = '`#` protected ones and `-` private ones.';
    private $privateProperty = 'Hovering a property shows a reminder.';
}

$var = new PropertyExample();
dump($var);

class DynamicPropertyExample
{
    public $declaredProperty = 'This property is declared in the class definition';
}

$var = new DynamicPropertyExample();
$var->undeclaredProperty = 'Runtime added dynamic properties have `"` around their name.';
dump($var);

class ReferenceExample
{
    public $info = "Circular and sibling references are displayed as `#number`.nHovering them highlights all instances in the same dump.n";
}
$var = new ReferenceExample();
$var->aCircularReference = $var;
dump($var);

$var = new ErrorException(
    "For some objects, properties have special valuesn"
    ."that are best represented as constants, liken"
    ."`severity` below. Hovering displays the value (`2`).n",
    0,
    E_WARNING
);
dump($var);

$var = array();
$var[0] = 1;
$var[1] =& $var[0];
$var[1] += 1;
$var[2] = array("Hard references (circular or sibling)");
$var[3] =& $var[2];
$var[3][] = "are dumped using `&number` prefixes.";
dump($var);

$var = new ArrayObject();
$var[] = "Some resources and special objects like the current";
$var[] = "one are sometimes best represented using virtual";
$var[] = "properties that describe their internal state.";
dump($var);

$var = new AcmeController(
    "When a dump goes over its maximum items limit,n"
    ."or when some special objects are encountered,n"
    ."children can be replaced by an ellipsis andn"
    ."optionally followed by a number that says hown"
    ."many have been removed; `9` in this case.n"
);
dump($var);