@@ -34,8 +34,7 @@ A cloner is used to create an intermediate representation of any PHP variable.
3434Its output is a:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data `
3535object that wraps this representation.
3636
37- You can create a:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data `
38- object this way::
37+ You can create a ``Data `` object this way::
3938
4039 use Symfony\Component\VarDumper\Cloner\VarCloner;
4140
@@ -45,8 +44,11 @@ object this way::
4544 // see the example at the top of this page
4645 // $dumper->dump($data);
4746
48- A cloner also applies limits when creating the representation, so that the
49- corresponding Data object could represent only a subset of the cloned variable.
47+ Whatever the cloned data structure, resulting ``Data `` objects are always
48+ serializable.
49+
50+ A cloner applies limits when creating the representation, so that the one
51+ can represent only a subset of the cloned variable.
5052Before calling:method: `Symfony\\ Component\\ VarDumper\\ Cloner\\ VarCloner::cloneVar `,
5153you can configure these limits:
5254
@@ -154,6 +156,14 @@ Another option for doing the same could be::
154156
155157 // $output is now populated with the dump representation of $variable
156158
159+ ..versionadded ::3.2
160+
161+ You can pass ``true `` to the 2nd argument of the
162+ :method: `Symfony\\ Component\\ VarDumper\\ Dumper\\ AbstractDumper::dump `
163+ method to make it return the dump as string::
164+
165+ $output = $dumper->dump($cloner->cloneVar($variable), true);
166+
157167Dumpers implement the:class: `Symfony\\ Component\\ VarDumper\\ Dumper\\ DataDumperInterface `
158168interface that specifies the
159169:method: `dump(Data $data) <Symfony\\ Component\\ VarDumper\\ Dumper\\ DataDumperInterface::dump> `
@@ -167,7 +177,7 @@ Casters
167177
168178Objects and resources nested in a PHP variable are "cast" to arrays in the
169179intermediate:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Data `
170- representation. You cantweak the array representation for each object/resource
180+ representation. You canspecialize the array representation for each object/resource
171181by hooking a Caster into this process. The component already includes many
172182casters for base PHP classes and other common classes.
173183
@@ -203,17 +213,21 @@ can also be registered for the same resource type/class/interface.
203213They are called in registration order.
204214
205215Casters are responsible for returning the properties of the object or resource
206- being cloned in an array. They are callables that acceptfour arguments:
216+ being cloned in an array. They are callables that acceptfive arguments:
207217
208218* the object or resource being casted,
209219* an array modelled for objects after PHP's native ``(array) `` cast operator,
210220* a:class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Stub ` object
211221 representing the main properties of the object (class, type, etc.),
212- * true/false when the caster is called nested in a structure or not.
222+ * true/false when the caster is called nested in a structure or not,
223+ * A bit field of:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ Caster`` `::EXCLUDE_*``
224+ constants.
213225
214226Here is a simple caster not doing anything::
215227
216- function myCaster($object, $array, $stub, $isNested)
228+ use Symfony\Component\VarDumper\Cloner\Stub;
229+
230+ function myCaster($object, $array, Stub $stub, $isNested, $filter)
217231 {
218232 // ... populate/alter $array to your needs
219233
@@ -240,3 +254,49 @@ properties not in the class declaration).
240254..tip ::
241255
242256 Before writing your own casters, you should check the existing ones.
257+
258+ Adding semantics with metadata
259+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260+
261+ ..versionadded ::3.2
262+
263+ As of Symfony 3.2, casters can attach metadata attributes to
264+ :class: `Symfony\\ Component\\ VarDumper\\ Cloner\\ Stub ` objects to inform
265+ dumpers about the precise type of the dumped values.
266+
267+ Since casters are hooked on specific classes or interfaces, they know about the
268+ objects they manipulate. By altering the ``$stub `` object (the 3rd argument of
269+ any casters), one can transfer this knowledge to the resulting ``Data `` object,
270+ thus to dumpers. To help you do this (see the source code for how it works),
271+ the component comes with a set of wrappers for common additional semantics. You
272+ can use:
273+
274+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ ConstStub ` to wrap a value that is
275+ best represented by a PHP constant;
276+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ CutStub ` to replace big noisy
277+ objects/strings/*etc. * by ellipses;
278+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ CutArrayStub ` to keep only some
279+ useful keys of an array;
280+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ EnumStub ` to wrap a set of virtual
281+ values (*i.e. * values that do not exist as properties in the original PHP data
282+ structure, but are worth listing alongside with real ones);
283+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ LinkStub ` to wrap strings that can
284+ be turned into links by dumpers;
285+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ TraceStub ` and their
286+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ FrameStub ` and
287+ *:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ ArgsStub ` relatives to wrap PHP
288+ traces (used by:class: `Symfony\\ Component\\ VarDumper\\ Caster\\ ExceptionCaster `).
289+
290+ For example, if you know that your ``Foo `` objects have a ``target `` property
291+ that holds a file name or a URL, you can wrap them in a ``LinkStub `` to tell
292+ ``HtmlDumper `` to make them clickable::
293+
294+ use Symfony\Component\VarDumper\Caster\LinkStub;
295+ use Symfony\Component\VarDumper\Cloner\Stub;
296+
297+ function myFooCaster(\Foo $object, $array, Stub $stub, $isNested, $filter = 0)
298+ {
299+ $array['target'] = new LinkStub($array['target']);
300+
301+ return $array;
302+ }