|
| 1 | +.. index:: |
| 2 | + single: VarDumper |
| 3 | + single: Components; VarDumper |
| 4 | + |
| 5 | +The VarDumper Component |
| 6 | +======================= |
| 7 | + |
| 8 | + The VarDumper component provides mechanisms for walking through any arbitrary PHP variable. |
| 9 | + Built on top, it provides a better ``dump()`` function, that you can use instead of ``var_dump()``, |
| 10 | + *better* meaning: |
| 11 | + |
| 12 | + - per object and resource types specialized view to e.g. filter out Doctrine noise |
| 13 | + while dumping a single proxy entity, or get more insight on opened files with |
| 14 | + ``stream_get_meta_data()``. |
| 15 | + - configurable output format: HTML, command line with colors or JSON. |
| 16 | + - ability to dump internal references, either soft ones (objects or resources) |
| 17 | + or hard ones (``=&`` on arrays or objects properties). Repeated occurrences of |
| 18 | + the same object/array/resource won't appear again and again anymore. Moreover, |
| 19 | + you'll be able to inspected the reference structure of your data. |
| 20 | + - ability to operate in the context of an output buffering handler. |
| 21 | + |
| 22 | +.. versionadded:: 2.6 |
| 23 | + The VarDumper component was introduced in Symfony 2.6. |
| 24 | + |
| 25 | +Installation |
| 26 | +------------ |
| 27 | + |
| 28 | +You can install the component in 2 different ways: |
| 29 | + |
| 30 | +* :doc:`Install it via Composer </components/using_components>` (``symfony/var-dumper`` on `Packagist`_); |
| 31 | +* Use the official Git repository (https://github.com/symfony/VarDumper). |
| 32 | + |
| 33 | +The dump() function |
| 34 | +------------------- |
| 35 | + |
| 36 | +The VarDumper component creates a global ``dump()`` function that is auto-configured out of the box: |
| 37 | +HTML or CLI output is automatically selected based on the current PHP SAPI. |
| 38 | + |
| 39 | +``dump()`` is just a thin wrapper for ``\Symfony\Component\VarDumper\VarDumper::dump()`` so can you also use it directly. |
| 40 | +You can change the behavior of this function by calling ``\Symfony\Component\VarDumper\VarDumper::setHandler($callable)``: |
| 41 | +calls to ``dump()`` will then be forwarded to the ``$callable`` given as first argument. |
| 42 | + |
| 43 | +Advanced usage |
| 44 | +-------------- |
| 45 | + |
| 46 | +Cloners |
| 47 | +~~~~~~~ |
| 48 | + |
| 49 | +A cloner is used to create an intermediate representation of any PHP variable. |
| 50 | +Its output is a Data object that wraps this representation. |
| 51 | +A cloner also applies limits when creating the representation, so that the corresponding |
| 52 | +Data object could represent only a subset of the cloned variable. |
| 53 | + |
| 54 | +You can create a Data object this way:: |
| 55 | + |
| 56 | + $cloner = new PhpCloner(); |
| 57 | + $data = $cloner->cloneVar($myVar); |
| 58 | + |
| 59 | +Before cloning, you can configure the limits with:: |
| 60 | + |
| 61 | + $cloner->setMaxItems($number); |
| 62 | + $cloner->setMaxString($number); |
| 63 | + |
| 64 | +These limits will be applied when calling ``->cloneVar()`` afterwise. |
| 65 | + |
| 66 | +Casters |
| 67 | +~~~~~~~ |
| 68 | + |
| 69 | +Objects and resources nested in a PHP variable are casted to arrays in the intermediate Data representation. |
| 70 | +You can tweak the array representation for each object/resource by hooking a Caster into this process. |
| 71 | +The component already has a many casters for base PHP classes and other common classes. |
| 72 | + |
| 73 | +If you want to build your how Caster, you can register one before cloning a PHP variable. |
| 74 | +Casters are registered using either a Cloner's constructor or its ``addCasters()`` method:: |
| 75 | + |
| 76 | + $myCasters = array(...); |
| 77 | + $cloner = new PhpCloner($myCasters); |
| 78 | + |
| 79 | +or:: |
| 80 | + |
| 81 | + $cloner->addCasters($myCasters); |
| 82 | + |
| 83 | +The provided ``$myCasters`` argument is an array that maps a class, an interface or a resource type to a callable:: |
| 84 | + |
| 85 | + $myCasters = array( |
| 86 | + 'FooClass' => $myFooClassCallableCaster, |
| 87 | + ':bar resource' => $myBarResourceCallableCaster, |
| 88 | + ); |
| 89 | + |
| 90 | +As you can notice, resource types are prefixed by a ``:`` to prevent colliding with a class name. |
| 91 | + |
| 92 | +Because an object has one main class and potentially many parent classes or interfaces, |
| 93 | +many casters can be applied to one object. In this case, casters are called one after the other, |
| 94 | +starting from casters bound to the interfaces, the parents classes and then the main class. |
| 95 | +Several casters can also be registered for the same resource type/class/interface. |
| 96 | +They are called in registration order. |
| 97 | + |
| 98 | +Casters are responsible for returning the properties of the object or resource being cloned in an array. |
| 99 | +They are callables that accept four arguments:: |
| 100 | + |
| 101 | + /** |
| 102 | + * A caster not doing anything. |
| 103 | + * |
| 104 | + * @param object|resource $object The object or resource being casted. |
| 105 | + * @param array $array An array modelled for objects after PHP's native `(array)` cast operator. |
| 106 | + * @param Stub $stub A Cloner\Stub object representing the main properties of $object (class, type, etc.). |
| 107 | + * @param bool $isNested True/false when the caster is called nested is a structure or not. |
| 108 | + * |
| 109 | + * @return array The properties of $object casted in an array. |
| 110 | + */ |
| 111 | + function myCaster($origValue, $array, $stub, $isNested) |
| 112 | + { |
| 113 | + // Here, populate/alter $array to your needs. |
| 114 | + |
| 115 | + return $array; |
| 116 | + } |
| 117 | + |
| 118 | +For objects, the ``$array`` parameter comes pre-populated with PHP's native ``(array)`` casting operator, |
| 119 | +or with the return value of ``$object->__debugInfo()`` if the magic method exists. |
| 120 | +Then, the return value of one Caster is given as argument to the next Caster in the chain. |
| 121 | + |
| 122 | +When casting with the ``(array)`` operator, PHP prefixes protected properties with a ``\0*\0`` |
| 123 | +and private ones with the class owning the property: e.g. ``\0Foobar\0`` prefixes all private properties |
| 124 | +of objects of type Foobar. Casters follow this convention and add two more prefixes: ``\0~\0`` is used for |
| 125 | +virtual properties and ``\0+\0`` for dynamic ones (runtime added properties not in the class declaration). |
| 126 | + |
| 127 | +.. note:: |
| 128 | + |
| 129 | + Although you can, it is best advised not to alter the state of an object while casting it in a Caster. |
| 130 | + |
| 131 | +Dumpers |
| 132 | +~~~~~~~ |
| 133 | + |
| 134 | +.. _Packagist: https://packagist.org/packages/symfony/var-dumper |
0 commit comments