intro the var-dumper component

Author: nicolas-grekas

components/index.rst

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

components/map.rst.inc

@@ -143,6 +143,10 @@
   * :doc:`/components/translation/usage`
   * :doc:`/components/translation/custom_formats`
 
+* **VarDumper**
+
+  * :doc:`/components/var_dumper`
+
 * :doc:`/components/yaml/index`
 
   * :doc:`/components/yaml/introduction`

components/var_dumper.rst

@@ -0,0 +1,104 @@
+.. index::
+   single: VarDumper
+   single: Components; VarDumper
+
+The VarDumper Component
+=======================
+
+    The VarDumper component provides mechanisms for walking through any arbitrary PHP variable.
+    Built on top, it provides a better ``dump()`` function, that you can use instead of ``var_dump()``,
+    *better* meaning:
+
+    - per object and resource types specialized view to e.g. filter out Doctrine noise
+      while dumping a single proxy entity, or get more insight on opened files with
+      ``stream_get_meta_data()``.
+    - configurable output format: HTML, command line with colors or JSON.
+    - 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 inspected the reference structure of your data.
+    - ability to operate in the context of an output buffering handler.
+
+.. versionadded:: 2.6
+    The VarDumper component was introduced in Symfony 2.6.
+
+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).
+
+The dump() function
+-------------------
+
+The VarDumper component creates a global ``dump()`` function that is auto-configured out of the box:
+HTML or CLI output is automatically selected based on the current PHP SAPI.
+
+``dump()`` is just a thin wrapper for ``\Symfony\Component\VarDumper\VarDumper::dump()`` so can you also use it directly.
+You can change the behavior of this function by calling ``\Symfony\Component\VarDumper\VarDumper::setHandler($callable)``:
+calls to ``dump()`` will then be forwarded to the ``$callable`` given as first argument.
+
+Advanced usage
+--------------
+
+Cloners
+~~~~~~~
+
+A cloner is used to create an intermediate representation of any PHP variable. 
+Its output is a Data object that wraps this representation.
+A cloner also applies limits when creating the representation, so that the corresponding
+Data object represents only a subset of the cloned variable.
+
+You can create a Data object this way::
+
+    $cloner = new PhpCloner();
+    $data = $cloner->cloneVar($myVar);
+
+Before cloning, you can configure the limits with::
+
+    $cloner->setMaxItems($number);
+    $cloner->setMaxString($number);
+
+These limits will be applied when calling ``->cloneVar()`` afterwise.
+
+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 has a many casters for base PHP classes and other common classes.
+
+If you want to build your how Caster, you can register one before cloning a PHP variable.
+Casters are registered either using a Cloner's constructor or its ``addCasters()`` method::
+
+    $myCasters = array(...);
+    $cloner = new PhpCloner($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.
+
+One and only one caster can be registered per resource type/class/interface.
+But 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.
+
+.. note::
+
+    Although you can, it is best advised not to alter the state of an object while casting it in a Caster.
+
+Dumpers
+~~~~~~~
+
+.. _Packagist: https://packagist.org/packages/symfony/var-dumper