Skip to content

Commit 26edf7a

Browse files
nicolas-grekasnicolas-grekas
committed
intro the var-dumper component
1 parent a3400fd commit 26edf7a

File tree

3 files changed

+139
-0
lines changed

3 files changed

+139
-0
lines changed

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ The Components
2929
stopwatch
3030
templating/index
3131
translation/index
32+
var_dumper
3233
yaml/index
3334

3435
.. include:: /components/map.rst.inc

‎components/map.rst.inc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,10 @@
143143
* :doc:`/components/translation/usage`
144144
* :doc:`/components/translation/custom_formats`
145145

146+
* **VarDumper**
147+
148+
* :doc:`/components/var_dumper`
149+
146150
* :doc:`/components/yaml/index`
147151

148152
* :doc:`/components/yaml/introduction`

‎components/var_dumper.rst

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
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

Comments
 (0)