Advanced Usage of the VarDumper Component
Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.2 (the current stable version).
The dump()
function is just a thin wrapper and a more convenient way to call
VarDumper::dump().
You can change the behavior of this function by calling
VarDumper::setHandler($callable).
Calls to dump()
will then be forwarded to $callable
.
By adding a handler, you can customize the Cloners, Dumpers and Casters as explained below. A simple implementation of a handler function might look like this:
1 2 3 4 5 6 7 8 9 10 11
use Symfony\Component\VarDumper\VarDumper;
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
use Symfony\Component\VarDumper\Dumper\HtmlDumper;
VarDumper::setHandler(function ($var) {
$cloner = new VarCloner();
$dumper = 'cli' === PHP_SAPI ? new CliDumper() : new HtmlDumper();
$dumper->dump($cloner->cloneVar($var));
});
Cloners
A cloner is used to create an intermediate representation of any PHP variable. Its output is a Data object that wraps this representation.
You can create a Data object this way:
1 2 3 4 5 6 7
use Symfony\Component\VarDumper\Cloner\VarCloner;
$cloner = new VarCloner();
$data = $cloner->cloneVar($myVar);
// this is commonly then passed to the dumper
// see the example at the top of this page
// $dumper->dump($data);
A cloner also applies limits when creating the representation, so that the corresponding Data object could represent only a subset of the cloned variable. Before calling cloneVar(), you can configure these limits:
- setMaxItems()
- configures the maximum number of items that will be cloned past the first nesting level. Items are counted using a breadth-first algorithm so that lower level items have higher priority than deeply nested items;
- setMaxString()
- configures the maximum number of characters that will be cloned before cutting overlong strings;
In both cases, specifying -1
removes any limit.
Before dumping it, you can further limit the resulting Data object using the following methods:
- withMaxDepth()
- Allows limiting dumps in the depth dimension.
- withMaxItemsPerDepth()
- Limits the number of items per depth level.
- withRefHandles()
- Allows removing internal objects' handles for sparser output (useful for tests).
Unlike the previous limits on cloners that remove data on purpose, these can be changed back and forth before dumping since they do not affect the intermediate representation internally.
Dumpers
A dumper is responsible for outputting a string representation of a PHP variable, using a Data object as input. The destination and the formatting of this output vary with dumpers.
This component comes with an HtmlDumper for HTML output and a CliDumper for optionally colored command line output.
For example, if you want to dump some $variable
, just do:
1 2 3 4 5 6 7
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
$cloner = new VarCloner();
$dumper = new CliDumper();
$dumper->dump($cloner->cloneVar($variable));
By using the first argument of the constructor, you can select the output
stream where the dump will be written. By default, the CliDumper
writes
on php://stdout
and the HtmlDumper
on php://output
. But any PHP
stream (resource or URL) is acceptable.
Instead of a stream destination, you can also pass it a callable
that
will be called repeatedly for each line generated by a dumper. This
callable can be configured using the first argument of a dumper's constructor,
but also using the
setOutput()
method or the second argument of the
dump() method.
For example, to get a dump as a string in a variable, you can do:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
$cloner = new VarCloner();
$dumper = new CliDumper();
$output = '';
$dumper->dump(
$cloner->cloneVar($variable),
function ($line, $depth) use (&$output) {
// A negative depth means "end of dump"
if ($depth >= 0) {
// Adds a two spaces indentation to the line
$output .= str_repeat(' ', $depth).$line."\n";
}
}
);
// $output is now populated with the dump representation of $variable
Another option for doing the same could be:
1 2 3 4 5 6 7 8 9 10 11
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
$cloner = new VarCloner();
$dumper = new CliDumper();
$output = fopen('php://memory', 'r+b');
$dumper->dump($cloner->cloneVar($variable), $output);
$output = stream_get_contents($output, -1, 0);
// $output is now populated with the dump representation of $variable
Dumpers implement the DataDumperInterface interface that specifies the dump(Data $data) method. They also typically implement the DumperInterface that frees them from re-implementing the logic required to walk through a Data object's internal structure.
Casters
Objects and resources nested in a PHP variable are "cast" to arrays in the intermediate Data representation. You can tweak the array representation for each object/resource by hooking a Caster into this process. The component already includes many casters for base PHP classes and other common classes.
If you want to build your own Caster, you can register one before cloning
a PHP variable. Casters are registered using either a Cloner's constructor
or its addCasters()
method:
1 2 3 4 5 6 7 8
use Symfony\Component\VarDumper\Cloner\VarCloner;
$myCasters = array(...);
$cloner = new VarCloner($myCasters);
// or
$cloner->addCasters($myCasters);
The provided $myCasters
argument is an array that maps a class,
an interface or a resource type to a callable:
1 2 3 4
$myCasters = array(
'FooClass' => $myFooClassCallableCaster,
':bar resource' => $myBarResourceCallableCaster,
);
As you can notice, resource types are prefixed by a :
to prevent
colliding with a class name.
Because an object has one main class and potentially many parent classes or interfaces, many casters can be applied to one object. In this case, casters are called one after the other, starting from casters bound to the interfaces, the parents classes and then the main class. Several casters can also be registered for the same resource type/class/interface. They are called in registration order.
Casters are responsible for returning the properties of the object or resource being cloned in an array. They are callables that accept four arguments:
- the object or resource being casted,
- an array modelled for objects after PHP's native
(array)
cast operator, - a Stub object representing the main properties of the object (class, type, etc.),
- true/false when the caster is called nested in a structure or not.
Here is a simple caster not doing anything:
1 2 3 4 5 6
function myCaster($object, $array, $stub, $isNested)
{
// ... populate/alter $array to your needs
return $array;
}
For objects, the $array
parameter comes pre-populated using PHP's native
(array)
casting operator or with the return value of $object->__debugInfo()
if the magic method exists. Then, the return value of one Caster is given
as the array argument to the next Caster in the chain.
When casting with the (array)
operator, PHP prefixes protected properties
with a \0*\0
and private ones with the class owning the property. For example,
\0Foobar\0
will be the prefix for all private properties of objects of
type Foobar. Casters follow this convention and add two more prefixes: \0~\0
is used for virtual properties and \0+\0
for dynamic ones (runtime added
properties not in the class declaration).
Note
Although you can, it is advised to not alter the state of an object while casting it in a Caster.
Tip
Before writing your own casters, you should check the existing ones.