Oct 14, 2016 · Sep 2, 2016 · Sep 2, 2016 · Sep 2, 2016 · Sep 3, 2016 · Sep 3, 2016
diff --git a/components/var_dumper.rst b/components/var_dumper.rst
 The VarDumper Component
 =======================

    The VarDumper component provides mechanisms forwalking through any
 arbitrary PHPvariable. Built on top, it provides a better ``dump()``
 functionthat you can use instead of:phpfunction:`var_dump`.
    The VarDumper component provides mechanisms forextracting the state out of
 any PHPvariables. Built on top, it provides a better ``dump()`` function
    that you can use instead of:phpfunction:`var_dump`.

 Installation
 ------------
diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst
 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::
 You can create a ``Data`` object this way::

    use Symfony\Component\VarDumper\Cloner\VarCloner;

    // see the example at the top of this page
    // $dumper->dump($data);

 A cloner also applies limits when creating the representation, so that the
 corresponding Data object could represent only a subset of the cloned variable.
 Whatever the cloned data structure, resulting ``Data`` objects are always
 serializable.

 A cloner applies limits when creating the representation, so that one
 can represent only a subset of the cloned variable.
 Before calling :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::cloneVar`,
 you can configure these limits:


    // $output is now populated with the dump representation of $variable

 .. tip::

    You can pass ``true`` to the second argument of the
    :method:`Symfony\\Component\\VarDumper\\Dumper\\AbstractDumper::dump`
    method to make it return the dump as a string::

        $output = $dumper->dump($cloner->cloneVar($variable), true);

    .. versionadded:: 3.2
        The ability to return a string was introduced in Symfony 3.2.

 Dumpers implement the :class:`Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface`
 interface that specifies the
 :method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`

 Objects and resources nested in a PHP variable are "cast" to arrays in the
 intermediate :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
 representation. You cantweak the array representation for each object/resource
 representation. You cancustomize 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.

 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 acceptfour arguments:
 being cloned in an array. They are callables that acceptfive arguments:

 * the object or resource being casted,
 * an array modelled for objects after PHP's native ``(array)`` cast operator,
 * 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 in a structure or not.
  representing the main properties of the object (class, type, etc.);
 * true/false when the caster is called nested in a structure or not;
 * A bit field of :class:`Symfony\\Component\\VarDumper\\Caster\\Caster```::EXCLUDE_*``
  constants.

 Here is a simple caster not doing anything::

    function myCaster($object, $array, $stub, $isNested)
    use Symfony\Component\VarDumper\Cloner\Stub;

    function myCaster($object, $array, Stub $stub, $isNested, $filter)
    {
        // ... populate/alter $array to your needs

 .. tip::

    Before writing your own casters, you should check the existing ones.

 Adding Semantics with Metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. versionadded:: 3.2
    As of Symfony 3.2, casters can attach metadata attributes to
    :class:`Symfony\\Component\\VarDumper\\Cloner\\Stub` objects to inform
    dumpers about the precise type of the dumped values.

 Since casters are hooked on specific classes or interfaces, they know about the
 objects they manipulate. By altering the ``$stub`` object (the third argument of
 any caster), one can transfer this knowledge to the resulting ``Data`` object,
 thus to dumpers. To help you do this (see the source code for how it works),
 the component comes with a set of wrappers for common additional semantics. You
 can use:

 * :class:`Symfony\\Component\\VarDumper\\Caster\\ConstStub` to wrap a value that is
   best represented by a PHP constant;
 * :class:`Symfony\\Component\\VarDumper\\Caster\\ClassStub` to wrap a PHP identifier
   (*i.e.* a class name, a method name, an interface, *etc.*);
 * :class:`Symfony\\Component\\VarDumper\\Caster\\CutStub` to replace big noisy
   objects/strings/*etc.* by ellipses;
 * :class:`Symfony\\Component\\VarDumper\\Caster\\CutArrayStub` to keep only some
   useful keys of an array;
 * :class:`Symfony\\Component\\VarDumper\\Caster\\EnumStub` to wrap a set of virtual
   values (*i.e.* values that do not exist as properties in the original PHP data
   structure, but are worth listing alongside with real ones);
 * :class:`Symfony\\Component\\VarDumper\\Caster\\LinkStub` to wrap strings that can
   be turned into links by dumpers;
 * :class:`Symfony\\Component\\VarDumper\\Caster\\TraceStub` and their
 * :class:`Symfony\\Component\\VarDumper\\Caster\\FrameStub` and
 * :class:`Symfony\\Component\\VarDumper\\Caster\\ArgsStub` relatives to wrap PHP
   traces (used by :class:`Symfony\\Component\\VarDumper\\Caster\\ExceptionCaster`).

 For example, if you know that your ``Product`` objects have a ``brochure`` property
 that holds a file name or a URL, you can wrap them in a ``LinkStub`` to tell
 ``HtmlDumper`` to make them clickable::

    use Symfony\Component\VarDumper\Caster\LinkStub;
    use Symfony\Component\VarDumper\Cloner\Stub;

    function ProductCaster(Product $object, $array, Stub $stub, $isNested, $filter = 0)
    {
        $array['brochure'] = new LinkStub($array['brochure']);

        return $array;
    }
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,9 +5,9 @@
		The VarDumper Component
		=======================

		The VarDumper component provides mechanisms forwalking through any
		arbitrary PHPvariable. Built on top, it provides a better ``dump()``
		functionthat you can use instead of:phpfunction:`var_dump`.
		The VarDumper component provides mechanisms forextracting the state out of
Copy link Member javiereguiluzSep 2, 2016 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. `extracting the state` ->`extracting the contents` ? Copy link MemberAuthor nicolas-grekasSep 2, 2016 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. state = content + context/metadata javiereguiluz and apfelbox reacted with thumbs up emoji
		any PHPvariables. Built on top, it provides a better ``dump()`` function
		that you can use instead of:phpfunction:`var_dump`.

		Installation
		------------
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -34,8 +34,7 @@ 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::
		You can create a ``Data`` object this way::

		use Symfony\Component\VarDumper\Cloner\VarCloner;

Expand All		@@ -45,8 +44,11 @@ object this way::
		// see the example at the top of this page
		// $dumper->dump($data);

		A cloner also applies limits when creating the representation, so that the
		corresponding Data object could represent only a subset of the cloned variable.
		Whatever the cloned data structure, resulting ``Data`` objects are always
		serializable.

		A cloner applies limits when creating the representation, so that one
		can represent only a subset of the cloned variable.
		Before calling :method:`Symfony\\Component\\VarDumper\\Cloner\\VarCloner::cloneVar`,
		you can configure these limits:

Expand DownExpand Up		@@ -154,6 +156,17 @@ Another option for doing the same could be::

		// $output is now populated with the dump representation of $variable

		.. tip::

Copy link Member wouterjSep 3, 2016 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. this empty line has to be removed
		You can pass ``true`` to the second argument of the
		:method:`Symfony\\Component\\VarDumper\\Dumper\\AbstractDumper::dump`
		method to make it return the dump as a string::

		$output = $dumper->dump($cloner->cloneVar($variable), true);
Copy link Member wouterjSep 3, 2016 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. please rewrite this like: ..tip:: You can pass ``true`` to the second argument of the:method:`Symfony\\Component\\VarDumper\\Dumper\\AbstractDumper::dump` method to make it return the dump as a string:: $output = $dumper->dump($cloner->cloneVar($variable), true); ..versionadded::3.2 The ability to return as string was introduced in Symfony 3.2.

		.. versionadded:: 3.2
		The ability to return a string was introduced in Symfony 3.2.

		Dumpers implement the :class:`Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface`
		interface that specifies the
		:method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`
Expand All		@@ -167,7 +180,7 @@ Casters

		Objects and resources nested in a PHP variable are "cast" to arrays in the
		intermediate :class:`Symfony\\Component\\VarDumper\\Cloner\\Data`
		representation. You cantweak the array representation for each object/resource
		representation. You cancustomize 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.

Expand DownExpand Up		@@ -203,17 +216,21 @@ 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 acceptfour arguments:
		being cloned in an array. They are callables that acceptfive arguments:

		* the object or resource being casted,
		* an array modelled for objects after PHP's native ``(array)`` cast operator,
		* 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 in a structure or not.
		representing the main properties of the object (class, type, etc.);
		* true/false when the caster is called nested in a structure or not;
		* A bit field of :class:`Symfony\\Component\\VarDumper\\Caster\\Caster```::EXCLUDE_*``
		constants.

		Here is a simple caster not doing anything::

		function myCaster($object, $array, $stub, $isNested)
		use Symfony\Component\VarDumper\Cloner\Stub;

		function myCaster($object, $array, Stub $stub, $isNested, $filter)
		{
		// ... populate/alter $array to your needs

Expand All		@@ -240,3 +257,50 @@ properties not in the class declaration).
		.. tip::

		Before writing your own casters, you should check the existing ones.

		Adding Semantics with Metadata
		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		.. versionadded:: 3.2
		As of Symfony 3.2, casters can attach metadata attributes to
		:class:`Symfony\\Component\\VarDumper\\Cloner\\Stub` objects to inform
		dumpers about the precise type of the dumped values.

		Since casters are hooked on specific classes or interfaces, they know about the
		objects they manipulate. By altering the ``$stub`` object (the third argument of
		any caster), one can transfer this knowledge to the resulting ``Data`` object,
		thus to dumpers. To help you do this (see the source code for how it works),
		the component comes with a set of wrappers for common additional semantics. You
		can use:

		* :class:`Symfony\\Component\\VarDumper\\Caster\\ConstStub` to wrap a value that is
		best represented by a PHP constant;
		* :class:`Symfony\\Component\\VarDumper\\Caster\\ClassStub` to wrap a PHP identifier
		(i.e. a class name, a method name, an interface, etc.);
		* :class:`Symfony\\Component\\VarDumper\\Caster\\CutStub` to replace big noisy
		objects/strings/etc. by ellipses;
		* :class:`Symfony\\Component\\VarDumper\\Caster\\CutArrayStub` to keep only some
		useful keys of an array;
		* :class:`Symfony\\Component\\VarDumper\\Caster\\EnumStub` to wrap a set of virtual
		values (i.e. values that do not exist as properties in the original PHP data
		structure, but are worth listing alongside with real ones);
		* :class:`Symfony\\Component\\VarDumper\\Caster\\LinkStub` to wrap strings that can
		be turned into links by dumpers;
		* :class:`Symfony\\Component\\VarDumper\\Caster\\TraceStub` and their
		* :class:`Symfony\\Component\\VarDumper\\Caster\\FrameStub` and
		* :class:`Symfony\\Component\\VarDumper\\Caster\\ArgsStub` relatives to wrap PHP
		traces (used by :class:`Symfony\\Component\\VarDumper\\Caster\\ExceptionCaster`).

		For example, if you know that your ``Product`` objects have a ``brochure`` property
		that holds a file name or a URL, you can wrap them in a ``LinkStub`` to tell
		``HtmlDumper`` to make them clickable::

		use Symfony\Component\VarDumper\Caster\LinkStub;
		use Symfony\Component\VarDumper\Cloner\Stub;

		function ProductCaster(Product $object, $array, Stub $stub, $isNested, $filter = 0)
		{
		$array['brochure'] = new LinkStub($array['brochure']);

		return $array;
		}