doc for Dumpers

Author: nicolas-grekas

components/var_dumper.rst

@@ -17,8 +17,8 @@ Installation
 
 You can install the component in 2 different ways:
 
-* :doc:`Install it via Composer </components/using_components>` (``symfony/var-dumper`` on `Packagist`_);
-* Use the official Git repository (https://github.com/symfony/VarDumper).
+- :doc:`Install it via Composer </components/using_components>` (``symfony/var-dumper`` on `Packagist`_);
+- Use the official Git repository (https://github.com/symfony/var-dumper).
 
 The dump() function
 -------------------
@@ -29,19 +29,20 @@ on the current PHP SAPI.
 
 The advantages of this function are:
 
-    - per object and resource types specialized view to e.g. filter out
-      Doctrine internals while dumping a single proxy entity, or get more
-      insight on opened files with :phpfunction:`stream_get_meta_data()`.
-    - configurable output formats: HTML or colored command line output.
-    - ability to dump internal references, either soft ones (objects or
-      resources) or hard ones (``=&`` on arrays or objects properties).
-      Repeated occurrences of the same object/array/resource won't appear
-      again and again anymore. Moreover, you'll be able to inspect the
-      reference structure of your data.
-    - ability to operate in the context of an output buffering handler.
-
-``dump()`` is just a thin wrapper for :method:`VarDumper::dump()
-<Symfony\\Component\\VarDumper\\VarDumper::dump>` so can you also use it directly.
+- per object and resource types specialized view to e.g. filter out
+  Doctrine internals while dumping a single proxy entity, or get more
+  insight on opened files with :phpfunction:`stream_get_meta_data()`.
+- configurable output formats: HTML or colored command line output.
+- ability to dump internal references, either soft ones (objects or
+  resources) or hard ones (``=&`` on arrays or objects properties).
+  Repeated occurrences of the same object/array/resource won't appear
+  again and again anymore. Moreover, you'll be able to inspect the
+  reference structure of your data.
+- ability to operate in the context of an output buffering handler.
+
+``dump()`` is just a thin wrapper for
+:method:`VarDumper::dump() <Symfony\\Component\\VarDumper\\VarDumper::dump>`
+so can you also use it directly.
 You can change the behavior of this function by calling
 :method:`VarDumper::setHandler($callable) <Symfony\\Component\\VarDumper\\VarDumper::setHandler>`:
 calls to ``dump()`` will then be forwarded to ``$callable``, given as first argument.
@@ -53,12 +54,13 @@ Cloners
 ~~~~~~~
 
 A cloner is used to create an intermediate representation of any PHP variable.
-Its output is a :class:`Data <Symfony\\Component\\VarDumper\\Cloner\\Data>`
+Its output is a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
 object that wraps this representation. A cloner also applies limits when
 creating the representation, so that the corresponding Data object could
 represent only a subset of the cloned variable.
 
-You can create a Data object this way::
+You can create a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
+object this way::
 
     $cloner = new PhpCloner();
     $data = $cloner->cloneVar($myVar);
@@ -74,9 +76,10 @@ Casters
 ~~~~~~~
 
 Objects and resources nested in a PHP variable are casted 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.
+intermediate :class:`Symfony\\Component\\VarDumper\\Cloner\\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
@@ -107,14 +110,14 @@ 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 orresource
+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 :class:`Stub <Sumfony\\Component\\VarDumper\\Cloner\\Stub>` object
-      representing the main properties of the object (class, type, etc.),
-    - true/false when the caster is called nested is a structure or not.
+- the object or resource being casted,
+- an array modelled for objects after PHP's native ``(array)`` cast operator,
+- a :class:`Symfony\\Component\\VarDumper\\Cloner\\Stub` object
+  representing the main properties of the object (class, type, etc.),
+- true/false when the caster is called nested is a structure or not.
 
 Here is a simple caster not doing anything::
 
@@ -138,11 +141,65 @@ for virtual properties and ``\0+\0`` for dynamic ones (runtime added
 properties not in the class declaration).
 
 .. note::
-
     Although you can, it is best advised not to alter the state of an object
     while casting it in a Caster.
 
 Dumpers
 ~~~~~~~
 
+A dumper is responsible for outputting a string representation of a PHP variable,
+using a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object as input.
+The destination and the formatting of this output vary with dumpers.
+
+This component comes with an :class:`Symfony\\Component\\VarDumper\\Dumper\\HtmlDumper`
+for HTML output and a :class:`Symfony\\Component\\VarDumper\\Dumper\\CliDumper`
+for optionally colored command line output.
+
+For example, if you want to dump some ``$variable``, just do::
+
+    $cloner = new PhpCloner();
+    $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
+:method:`Symfony\\Component\\VarDumper\\Dumper\\AbstractDumper::setLineDumper`
+method or using the second argument of the
+:method:`Symfony\\Component\\VarDumper\\Dumper\\AbstractDumper::dump` method.
+
+For example, to get a dump in a variable, you can do::
+
+    $cloner = new PhpCloner();
+    $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
+
+Dumpers implement the :class:`Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface`
+interface that specifies the
+:method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`
+method. They also typically implement the
+:class:`Symfony\\Component\\VarDumper\\Cloner\\DumperInterface` that frees
+them from re-implementing the logic required to walk through a
+:class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object's internal structure.
+
 .. _Packagist: https://packagist.org/packages/symfony/var-dumper