feature #4243 [WIP] var-dumper component (nicolas-grekas)

This PR was merged into the master branch.

Discussion
----------

[WIP] var-dumper component

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | 2.6
| Fixed tickets | none

- [x] general introduction
- [x] cloner doc
- [x] caster doc
- [x] dumper doc
- [x] config doc
- [x] example output with explanations

Commits
-------

041e858 add examples
23712fb more accurate doc about limits
c578fe7 how to dump as string note
edb0ff9 minor adjustments
6a3e170 § about DebugBundle config
cb0ee89 § about Data::getLimitedClone()
ee2d7e4 section for DebugBundle/Twig integration
b5b45bc move Dumper section above the Caster one
2fc3811 use VarCloner instead of Php/ExtCloner
350e0c7 split intro/advanced sections
036edcb doc for Dumpers
7dc6e5c Reduce line length
5e0b9bd review effect
26edf7a intro the var-dumper component

components/index.rst

@@ -29,6 +29,7 @@ The Components
     stopwatch
     templating/index
     translation/index
+    var_dumper/index
     yaml/index
 
 .. include:: /components/map.rst.inc

components/map.rst.inc

@@ -144,6 +144,11 @@
   * :doc:`/components/translation/usage`
   * :doc:`/components/translation/custom_formats`
 
+* :doc:`/components/var_dumper/index`
+
+  * :doc:`/components/var_dumper/introduction`
+  * :doc:`/components/var_dumper/advanced`
+
 * :doc:`/components/yaml/index`
 
   * :doc:`/components/yaml/introduction`

components/var_dumper/advanced.rst

@@ -0,0 +1,205 @@
+.. index::
+   single: VarDumper
+   single: Components; VarDumper
+
+Advanced Usage of the VarDumper Component
+=========================================
+
+``dump()`` function is just a thin wrapper and a more convenient way to call
+:method:`VarDumper::dump() <Symfony\\Component\\VarDumper\\VarDumper::dump>`.
+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``.
+
+Cloners
+~~~~~~~
+
+A cloner is used to create an intermediate representation of any PHP variable.
+Its output is a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
+object that wraps this representation.
+
+You can create a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
+object this way::
+
+    $cloner = new VarCloner();
+    $data = $cloner->cloneVar($myVar);
+
+A cloner also applies limits when creating this representation, so that the
+corresponding Data object could represent only a subset of the cloned variable.
+Before :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::cloneVar`,
+you can configure these limits:
+
+* :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxItems`
+  configures the maximum number of items that will be cloned *past the first
+  nesting level*. Items are counted using a breadth-first algorithm so that
+  lower level items have higher priority than deeply nested items;
+* :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::setMaxString`
+  configures the maximum number of characters that will be cloned before
+  cutting overlong strings;
+* in both cases, specifying `-1` removes any limit.
+
+Before dumping it, you can further limit the resulting
+:class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object by calling its
+:method:`Symfony\\Component\\VarDumper\\Cloner\\Data::getLimitedClone`
+method:
+
+* the first ``$maxDepth`` argument allows limiting dumps in the depth dimension,
+* the second ``$maxItemsPerDepth`` limits the number of items per depth level,
+* and the last ``$useRefHandles`` defaults to ``true`` but allows removing
+  internal objects' handles for sparser output,
+* but unlike the previous limits on cloners that remove data on purpose,
+  these can be changed back and forth before dumping since they do not affect
+  the intermediate representation internally.
+
+.. note::
+
+    When no limit is applied, a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
+    object is as accurate as the native :phpfunction:`serialize` function
+    and thus could have a wider purpose than strictly dumping for debugging.
+
+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 VarCloner();
+    $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::setOutput`
+method or the second argument of the
+:method:`Symfony\\Component\\VarDumper\\Dumper\\AbstractDumper::dump` method.
+
+For example, to get a dump as a string in a variable, you can do::
+
+    $cloner = new VarCloner();
+    $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
+
+An other option for doing the same could be::
+
+    cloner = new VarCloner();
+    $dumper = new CliDumper();
+    $output = fopen('php://memory', 'r+b');
+
+    $dumper->dump($cloner->cloneVar($variable), $output);
+    rewind($output);
+    $output = stream_get_contents($output);
+
+    // $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.
+
+Casters
+~~~~~~~
+
+Objects and resources nested in a PHP variable are casted to arrays in the
+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
+or its ``addCasters()`` method::
+
+    $myCasters = array(...);
+    $cloner = new VarCloner($myCasters);
+
+    // or
+
+    $cloner->addCasters($myCasters);
+
+The provided ``$myCasters`` argument is an array that maps a class,
+an interface or a resource type to a callable::
+
+    $myCasters = array(
+        'FooClass' => $myFooClassCallableCaster,
+        ':bar resource' => $myBarResourceCallableCaster,
+    );
+
+As you can notice, resource types are prefixed by a ``:`` to prevent
+colliding with a class name.
+
+Because an object has one main class and potentially many parent classes
+or interfaces, many casters can be applied to one object. In this case,
+casters are called one after the other, starting from casters bound to the
+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 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:`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::
+
+    function myCaster($object, $array, $stub, $isNested)
+    {
+        // ... populate/alter $array to your needs
+
+        return $array;
+    }
+
+For objects, the ``$array`` parameter comes pre-populated using PHP's native
+``(array)`` casting operator or with the return value of ``$object->__debugInfo()``
+if the magic method exists. Then, the return value of one Caster is given
+as argument to the next Caster in the chain.
+
+When casting with the ``(array)`` operator, PHP prefixes protected properties
+with a ``\0*\0`` and private ones with the class owning the property:
+e.g. ``\0Foobar\0`` prefixes all private properties of objects of type Foobar.
+Casters follow this convention and add two more prefixes: ``\0~\0`` is used
+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.
+
+.. tip::
+
+    Before writting your own casters, you should check the existing ones.

components/var_dumper/index.rst

@@ -0,0 +1,8 @@
+VarDumper
+=========
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    advanced