@@ -17,8 +17,8 @@ Installation
1717
1818You can install the component in 2 different ways:
1919
20- * :doc: `Install it via Composer </components/using_components >` (``symfony/var-dumper `` on `Packagist `_);
21- * Use the official Git repository (https://github.com/symfony/VarDumper ).
20+ - :doc: `Install it via Composer </components/using_components >` (``symfony/var-dumper `` on `Packagist `_);
21+ - Use the official Git repository (https://github.com/symfony/var-dumper ).
2222
2323The dump() function
2424-------------------
@@ -29,19 +29,20 @@ on the current PHP SAPI.
2929
3030The advantages of this function are:
3131
32- - per object and resource types specialized view to e.g. filter out
33- Doctrine internals while dumping a single proxy entity, or get more
34- insight on opened files with:phpfunction: `stream_get_meta_data() `.
35- - configurable output formats: HTML or colored command line output.
36- - ability to dump internal references, either soft ones (objects or
37- resources) or hard ones (``=& `` on arrays or objects properties).
38- Repeated occurrences of the same object/array/resource won't appear
39- again and again anymore. Moreover, you'll be able to inspect the
40- reference structure of your data.
41- - ability to operate in the context of an output buffering handler.
42-
43- ``dump() `` is just a thin wrapper for:method: `VarDumper::dump()
44- <Symfony\\ Component\\ VarDumper\\ VarDumper::dump> ` so can you also use it directly.
32+ - per object and resource types specialized view to e.g. filter out
33+ Doctrine internals while dumping a single proxy entity, or get more
34+ insight on opened files with:phpfunction: `stream_get_meta_data() `.
35+ - configurable output formats: HTML or colored command line output.
36+ - ability to dump internal references, either soft ones (objects or
37+ resources) or hard ones (``=& `` on arrays or objects properties).
38+ Repeated occurrences of the same object/array/resource won't appear
39+ again and again anymore. Moreover, you'll be able to inspect the
40+ reference structure of your data.
41+ - ability to operate in the context of an output buffering handler.
42+
43+ ``dump() `` is just a thin wrapper for
44+ :method: `VarDumper::dump() <Symfony\\ Component\\ VarDumper\\ VarDumper::dump> `
45+ so can you also use it directly.
4546You can change the behavior of this function by calling
4647:method: `VarDumper::setHandler($callable) <Symfony\\ Component\\ VarDumper\\ VarDumper::setHandler> `:
4748calls to ``dump() `` will then be forwarded to ``$callable ``, given as first argument.
@@ -53,12 +54,13 @@ Cloners
5354~~~~~~~
5455
5556A cloner is used to create an intermediate representation of any PHP variable.
56- Its output is a:class: `Data < Symfony\\ Component\\ VarDumper\\ Cloner\\ Data>
57+ Its output is a:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data `
5758object that wraps this representation. A cloner also applies limits when
5859creating the representation, so that the corresponding Data object could
5960represent only a subset of the cloned variable.
6061
61- You can create a Data object this way::
62+ You can create a:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data `
63+ object this way::
6264
6365 $cloner = new PhpCloner();
6466 $data = $cloner->cloneVar($myVar);
@@ -74,9 +76,10 @@ Casters
7476~~~~~~~
7577
7678Objects and resources nested in a PHP variable are casted to arrays in the
77- intermediate Data representation. You can tweak the array representation for
78- each object/resource by hooking a Caster into this process. The component
79- already includes many casters for base PHP classes and other common classes.
79+ intermediate:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data `
80+ representation. You can tweak the array representation for each object/resource
81+ by hooking a Caster into this process. The component already includes many
82+ casters for base PHP classes and other common classes.
8083
8184If you want to build your own Caster, you can register one before cloning
8285a PHP variable. Casters are registered using either a Cloner's constructor
@@ -107,14 +110,14 @@ interfaces, the parents classes and then the main class. Several casters
107110can also be registered for the same resource type/class/interface.
108111They are called in registration order.
109112
110- Casters are responsible for returning the properties of the objectorresource
113+ Casters are responsible for returning the properties of the objector resource
111114being cloned in an array. They are callables that accept four arguments:
112115
113-
114- (array) `` cast operator,
115- :class: `Stub <Sumfony \\ Component\\ VarDumper\\ Cloner\\ Stub>
116-
117-
116+ - the object or resource being casted,
117+ - an array modelled for objects after PHP's native ``(array) `` cast operator,
118+ - a:class: `Symfony \\ Component\\ VarDumper\\ Cloner\\ Stub
119+ representing the main properties of the object (class, type, etc.),
120+ - true/false when the caster is called nested is a structure or not.
118121
119122Here is a simple caster not doing anything::
120123
@@ -138,11 +141,65 @@ for virtual properties and ``\0+\0`` for dynamic ones (runtime added
138141properties not in the class declaration).
139142
140143..note ::
141-
142144 Although you can, it is best advised not to alter the state of an object
143145 while casting it in a Caster.
144146
145147Dumpers
146148~~~~~~~
147149
150+ A dumper is responsible for outputting a string representation of a PHP variable,
151+ using a:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data ` object as input.
152+ The destination and the formatting of this output vary with dumpers.
153+
154+ This component comes with an:class: `Symfony\\ Component\\ VarDumper\\ Dumper\\ HtmlDumper `
155+ for HTML output and a:class: `Symfony\\ Component\\ VarDumper\\ Dumper\\ CliDumper `
156+ for optionally colored command line output.
157+
158+ For example, if you want to dump some ``$variable ``, just do::
159+
160+ $cloner = new PhpCloner();
161+ $dumper = new CliDumper();
162+
163+ $dumper->dump($cloner->cloneVar($variable));
164+
165+ By using the first argument of the constructor, you can select the output
166+ stream where the dump will be written. By default, the ``CliDumper `` writes
167+ on ``php://stdout `` and the ``HtmlDumper `` on ``php://output ``, but any PHP
168+ stream (resource or URL) is acceptable.
169+
170+ Instead of a stream destination, you can also pass it a ``callable `` that
171+ will be called repeatedly for each line generated by a dumper. This
172+ callable can be configured using the first argument of a dumper's constructor,
173+ but also using the
174+ :method: `Symfony\\ Component\\ VarDumper\\ Dumper\\ AbstractDumper::setLineDumper `
175+ method or using the second argument of the
176+ :method: `Symfony\\ Component\\ VarDumper\\ Dumper\\ AbstractDumper::dump ` method.
177+
178+ For example, to get a dump in a variable, you can do::
179+
180+ $cloner = new PhpCloner();
181+ $dumper = new CliDumper();
182+ $output = '';
183+
184+ $dumper->dump(
185+ $cloner->cloneVar($variable),
186+ function ($line, $depth) use (&$output) {
187+ // A negative depth means "end of dump"
188+ if ($depth >= 0) {
189+ // Adds a two spaces indentation to the line
190+ $output .= str_repeat(' ', $depth).$line."\n";
191+ }
192+ }
193+ );
194+
195+ // $output is now populated with the dump representation of $variable
196+
197+ Dumpers implement the:class: `Symfony\\ Component\\ VarDumper\\ Dumper\\ DataDumperInterface `
198+ interface that specifies the
199+ :method: `dump(Data $data) <Symfony\\ Component\\ VarDumper\\ Dumper\\ DataDumperInterface::dump> `
200+ method. They also typically implement the
201+ :class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ DumperInterface ` that frees
202+ them from re-implementing the logic required to walk through a
203+ :class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data ` object's internal structure.
204+
148205.. _Packagist :https://packagist.org/packages/symfony/var-dumper