From 26edf7ad4f2ada551c145cf81e7a3c9fccf5b567 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Wed, 17 Sep 2014 18:55:15 +0200 Subject: [PATCH 01/14] intro the var-dumper component --- components/index.rst | 1 + components/map.rst.inc | 4 ++ components/var_dumper.rst | 134 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+) create mode 100644 components/var_dumper.rst diff --git a/components/index.rst b/components/index.rst index 8e167cd2ac9..be74544ce43 100644 --- a/components/index.rst +++ b/components/index.rst @@ -29,6 +29,7 @@ The Components stopwatch templating/index translation/index + var_dumper yaml/index .. include:: /components/map.rst.inc diff --git a/components/map.rst.inc b/components/map.rst.inc index f9eab711e07..d3ce97a167f 100644 --- a/components/map.rst.inc +++ b/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` diff --git a/components/var_dumper.rst b/components/var_dumper.rst new file mode 100644 index 00000000000..01d8f237673 --- /dev/null +++ b/components/var_dumper.rst @@ -0,0 +1,134 @@ +.. 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 ` (``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 could represent 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 using either 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. + +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:: + + /** + * A caster not doing anything. + * + * @param object|resource $object The object or resource being casted. + * @param array $array An array modelled for objects after PHP's native `(array)` cast operator. + * @param Stub $stub A Cloner\Stub object representing the main properties of $object (class, type, etc.). + * @param bool $isNested True/false when the caster is called nested is a structure or not. + * + * @return array The properties of $object casted in an array. + */ + function myCaster($origValue, $array, $stub, $isNested) + { + // Here, populate/alter $array to your needs. + + return $array; + } + +For objects, the ``$array`` parameter comes pre-populated with 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. + +Dumpers +~~~~~~~ + +.. _Packagist: https://packagist.org/packages/symfony/var-dumper From 5e0b9bdc34ee60d1bb00e20d6949c03e38564371 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Tue, 30 Sep 2014 09:14:20 +0200 Subject: [PATCH 02/14] review effect --- components/var_dumper.rst | 76 ++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 37 deletions(-) diff --git a/components/var_dumper.rst b/components/var_dumper.rst index 01d8f237673..bcc1d66f139 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper.rst @@ -6,18 +6,8 @@ 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: + Built on top, it provides a better ``dump()`` function that you can use instead of :phpfunction:`var_dump`. - - 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. @@ -33,21 +23,34 @@ You can install the component in 2 different ways: The dump() function ------------------- -The VarDumper component creates a global ``dump()`` function that is auto-configured out of the box: +The VarDumper component creates a global ``dump()`` function that is 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. +The advantages of this function are: -Advanced usage + - 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() ` +so can you also use it directly. You can change the behavior of this function by calling +:method:`VarDumper::setHandler($callable) `: +calls to ``dump()`` will then be forwarded to ``$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. +Its output is a :class:`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. @@ -61,26 +64,27 @@ Before cloning, you can configure the limits with:: $cloner->setMaxItems($number); $cloner->setMaxString($number); -These limits will be applied when calling ``->cloneVar()`` afterwise. +They will be applied when calling ``->cloneVar()`` afterwards. 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. +The component already includes 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. +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 PhpCloner($myCasters); -or:: + // or $cloner->addCasters($myCasters); -The provided ``$myCasters`` argument is an array that maps a class, an interface or a resource type to a callable:: +The provided ``$myCasters`` argument is an array that maps a class, +an interface or a resource type to a callable:: $myCasters = array( 'FooClass' => $myFooClassCallableCaster, @@ -96,26 +100,24 @@ Several casters can also be registered for the same resource type/class/interfac 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:: - - /** - * A caster not doing anything. - * - * @param object|resource $object The object or resource being casted. - * @param array $array An array modelled for objects after PHP's native `(array)` cast operator. - * @param Stub $stub A Cloner\Stub object representing the main properties of $object (class, type, etc.). - * @param bool $isNested True/false when the caster is called nested is a structure or not. - * - * @return array The properties of $object casted in an array. - */ - function myCaster($origValue, $array, $stub, $isNested) +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 ` 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) { - // Here, populate/alter $array to your needs. + // ... populate/alter $array to your needs return $array; } -For objects, the ``$array`` parameter comes pre-populated with PHP's native ``(array)`` casting operator, +For objects, the ``$array`` parameter comes pre-populated with 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. From 7dc6e5cc24c522cab26cdcf38d954c26cc7a5c54 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Tue, 30 Sep 2014 12:05:55 +0200 Subject: [PATCH 03/14] Reduce line length --- components/var_dumper.rst | 90 ++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 39 deletions(-) diff --git a/components/var_dumper.rst b/components/var_dumper.rst index bcc1d66f139..db025c7cbfa 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper.rst @@ -5,9 +5,9 @@ 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 :phpfunction:`var_dump`. - + 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 :phpfunction:`var_dump`. .. versionadded:: 2.6 The VarDumper component was introduced in Symfony 2.6. @@ -23,23 +23,26 @@ You can install the component in 2 different ways: The dump() function ------------------- -The VarDumper component creates a global ``dump()`` function that is configured out of the box: -HTML or CLI output is automatically selected based on the current PHP SAPI. +The VarDumper component creates a global ``dump()`` function that is +configured out of the box: HTML or CLI output is automatically selected based +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()`. + - 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 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() ` -so can you also use it directly. You can change the behavior of this function by calling +``dump()`` is just a thin wrapper for :method:`VarDumper::dump() +` so can you also use it directly. +You can change the behavior of this function by calling :method:`VarDumper::setHandler($callable) `: calls to ``dump()`` will then be forwarded to ``$callable``, given as first argument. @@ -50,9 +53,10 @@ Cloners ~~~~~~~ A cloner is used to create an intermediate representation of any PHP variable. -Its output is a :class:`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. +Its output is a :class:`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:: @@ -69,12 +73,14 @@ They will be applied when calling ``->cloneVar()`` afterwards. 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. +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. -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:: +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 PhpCloner($myCasters); @@ -91,21 +97,23 @@ an interface or a resource type to a callable:: ':bar resource' => $myBarResourceCallableCaster, ); -As you can notice, resource types are prefixed by a ``:`` to prevent colliding with a class name. +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. +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: +Casters are responsible for returning the properties of the object orresource +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 ` object representing - the main properties of the object (class, type, etc.), + - a :class:`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:: @@ -117,18 +125,22 @@ Here is a simple caster not doing anything:: return $array; } -For objects, the ``$array`` parameter comes pre-populated with 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. +For objects, the ``$array`` parameter comes pre-populated with 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). +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. + Although you can, it is best advised not to alter the state of an object + while casting it in a Caster. Dumpers ~~~~~~~ From 036edcbcdcf9c6b48cc9c30dcff12377707874c6 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Wed, 1 Oct 2014 09:48:39 +0200 Subject: [PATCH 04/14] doc for Dumpers --- components/var_dumper.rst | 111 ++++++++++++++++++++++++++++---------- 1 file changed, 84 insertions(+), 27 deletions(-) diff --git a/components/var_dumper.rst b/components/var_dumper.rst index db025c7cbfa..b001162ed8a 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper.rst @@ -17,8 +17,8 @@ Installation You can install the component in 2 different ways: -* :doc:`Install it via Composer ` (``symfony/var-dumper`` on `Packagist`_); -* Use the official Git repository (https://github.com/symfony/VarDumper). +- :doc:`Install it via Composer ` (``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() -` 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() ` +so can you also use it directly. You can change the behavior of this function by calling :method:`VarDumper::setHandler($callable) `: 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 ` +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 ` 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) ` +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 From 350e0c7871bf05796954295757b981297676a4e1 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Fri, 3 Oct 2014 09:30:07 +0200 Subject: [PATCH 05/14] split intro/advanced sections --- components/index.rst | 2 +- components/map.rst.inc | 5 +- .../advanced.rst} | 51 +------------------ components/var_dumper/index.rst | 8 +++ components/var_dumper/introduction.rst | 50 ++++++++++++++++++ 5 files changed, 64 insertions(+), 52 deletions(-) rename components/{var_dumper.rst => var_dumper/advanced.rst} (75%) create mode 100644 components/var_dumper/index.rst create mode 100644 components/var_dumper/introduction.rst diff --git a/components/index.rst b/components/index.rst index be74544ce43..6386caab5df 100644 --- a/components/index.rst +++ b/components/index.rst @@ -29,7 +29,7 @@ The Components stopwatch templating/index translation/index - var_dumper + var_dumper/index yaml/index .. include:: /components/map.rst.inc diff --git a/components/map.rst.inc b/components/map.rst.inc index d3ce97a167f..93797c2e5d3 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -143,9 +143,10 @@ * :doc:`/components/translation/usage` * :doc:`/components/translation/custom_formats` -* **VarDumper** +* :doc:`/components/var_dumper/index` - * :doc:`/components/var_dumper` + * :doc:`/components/var_dumper/introduction` + * :doc:`/components/var_dumper/advanced` * :doc:`/components/yaml/index` diff --git a/components/var_dumper.rst b/components/var_dumper/advanced.rst similarity index 75% rename from components/var_dumper.rst rename to components/var_dumper/advanced.rst index b001162ed8a..ac384d8f181 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper/advanced.rst @@ -2,53 +2,8 @@ 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 :phpfunction:`var_dump`. - -.. 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 ` (``symfony/var-dumper`` on `Packagist`_); -- Use the official Git repository (https://github.com/symfony/var-dumper). - -The dump() function -------------------- - -The VarDumper component creates a global ``dump()`` function that is -configured out of the box: HTML or CLI output is automatically selected based -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() ` -so can you also use it directly. -You can change the behavior of this function by calling -:method:`VarDumper::setHandler($callable) `: -calls to ``dump()`` will then be forwarded to ``$callable``, given as first argument. - -Advanced Usage --------------- +Advanced Usage of the VarDumper Component +========================================= Cloners ~~~~~~~ @@ -201,5 +156,3 @@ 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 diff --git a/components/var_dumper/index.rst b/components/var_dumper/index.rst new file mode 100644 index 00000000000..2c67f2aa53f --- /dev/null +++ b/components/var_dumper/index.rst @@ -0,0 +1,8 @@ +VarDumper +========= + +.. toctree:: + :maxdepth: 2 + + introduction + advanced diff --git a/components/var_dumper/introduction.rst b/components/var_dumper/introduction.rst new file mode 100644 index 00000000000..1b4669cc83c --- /dev/null +++ b/components/var_dumper/introduction.rst @@ -0,0 +1,50 @@ +.. 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 :phpfunction:`var_dump`. + +.. 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 ` (``symfony/var-dumper`` on `Packagist`_); +- Use the official Git repository (https://github.com/symfony/var-dumper). + +The dump() function +------------------- + +The VarDumper component creates a global ``dump()`` function that is +configured out of the box: HTML or CLI output is automatically selected based +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() ` +so can you also use it directly. +You can change the behavior of this function by calling +:method:`VarDumper::setHandler($callable) `: +calls to ``dump()`` will then be forwarded to ``$callable``, given as first argument. + +.. _Packagist: https://packagist.org/packages/symfony/var-dumper From 2fc3811688f556946837df423a135c717fd267e2 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Tue, 7 Oct 2014 16:32:29 +0200 Subject: [PATCH 06/14] use VarCloner instead of Php/ExtCloner --- components/var_dumper/advanced.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst index ac384d8f181..d1c1609a229 100644 --- a/components/var_dumper/advanced.rst +++ b/components/var_dumper/advanced.rst @@ -17,7 +17,7 @@ represent only a subset of the cloned variable. You can create a :class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object this way:: - $cloner = new PhpCloner(); + $cloner = new VarCloner(); $data = $cloner->cloneVar($myVar); Before cloning, you can configure the limits with:: @@ -41,7 +41,7 @@ a PHP variable. Casters are registered using either a Cloner's constructor or its ``addCasters()`` method:: $myCasters = array(...); - $cloner = new PhpCloner($myCasters); + $cloner = new VarCloner($myCasters); // or @@ -112,7 +112,7 @@ for optionally colored command line output. For example, if you want to dump some ``$variable``, just do:: - $cloner = new PhpCloner(); + $cloner = new VarCloner(); $dumper = new CliDumper(); $dumper->dump($cloner->cloneVar($variable)); @@ -132,7 +132,7 @@ method or using the second argument of the For example, to get a dump in a variable, you can do:: - $cloner = new PhpCloner(); + $cloner = new VarCloner(); $dumper = new CliDumper(); $output = ''; From b5b45bccfe74d3c7a13660f01d4388240bd0f114 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Tue, 21 Oct 2014 08:52:28 +0200 Subject: [PATCH 07/14] move Dumper section above the Caster one --- components/var_dumper/advanced.rst | 116 ++++++++++++++--------------- 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst index d1c1609a229..bf15c1bfe79 100644 --- a/components/var_dumper/advanced.rst +++ b/components/var_dumper/advanced.rst @@ -27,6 +27,64 @@ Before cloning, you can configure the limits with:: They will be applied when calling ``->cloneVar()`` afterwards. +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::setLineDumper` +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 + +Dumpers implement the :class:`Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface` +interface that specifies the +:method:`dump(Data $data) ` +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 ~~~~~~~ @@ -98,61 +156,3 @@ 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 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::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 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 - -Dumpers implement the :class:`Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface` -interface that specifies the -:method:`dump(Data $data) ` -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. From ee2d7e473df3fea1929ca44bff1559cfb4b03276 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Wed, 29 Oct 2014 10:10:58 +0100 Subject: [PATCH 08/14] section for DebugBundle/Twig integration --- components/var_dumper/advanced.rst | 12 +++++++ components/var_dumper/introduction.rst | 48 +++++++++++++++++++++++++- 2 files changed, 59 insertions(+), 1 deletion(-) diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst index bf15c1bfe79..c0b3dd9c953 100644 --- a/components/var_dumper/advanced.rst +++ b/components/var_dumper/advanced.rst @@ -77,6 +77,18 @@ For example, to get a dump as a string in a variable, you can do:: // $output is now populated with the dump representation of $variable +An other option for doing the same could be:: + + $output = fopen('php://memory', 'r+b'); + cloner = new VarCloner(); + $dumper = new CliDumper($output); + + $dumper->dump($cloner->cloneVar($variable)); + fseek($output, 0); + $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) ` diff --git a/components/var_dumper/introduction.rst b/components/var_dumper/introduction.rst index 1b4669cc83c..bd48be2809d 100644 --- a/components/var_dumper/introduction.rst +++ b/components/var_dumper/introduction.rst @@ -45,6 +45,52 @@ The advantages of this function are: so can you also use it directly. You can change the behavior of this function by calling :method:`VarDumper::setHandler($callable) `: -calls to ``dump()`` will then be forwarded to ``$callable``, given as first argument. +calls to ``dump()`` will then be forwarded to ``$callable``. + +Where does the output go? +------------------------- + +If you read the advanced documentation, you'll learn how to change the +format or redirect the output to wherever you want. + +By default, these are selected based on your current PHP SAPI: + +- on the command line (CLI SAPI), the output is written on `STDERR`. This + can be surprising to some because this bypasses PHP's output buffering + mechanism. On the other hand, this give the possibility to easily split + dumps from regular output by using pipe redirection. +- on other SAPIs, dumps are written as HTML on the regular output. + +DebugBundle and Twig integration +-------------------------------- + +The `DebugBundle` allows greater integration of the component into the +Symfony full stack framework. It is enabled by default in the dev +environement of the standard edition since version 2.6. + +Since generating (even debug) output in the controller or in the model +of your application may just break it by e.g. sending HTTP headers or +corrupting your view, the bundle configures the `dump()` function so that +variables are dumped in the web debug toolbar. + +But if the toolbar can not be displayed because you e.g. called `die`/`exit` +or a fatal error occurred, then dumps are written on the regular output. + +In a Twig template, two constructs are available for dumping a variable. +Choosing between both is generally only a matter of personal taste: + +- `{% dump foo.bar %}` is the way to go when the original template output + shall not be modified: variables are not dumped inline, but in the web + debug toolbar. +- on the contrary, `{{ dump(foo.bar) }}` dumps inline and thus may or not + be suited to your use case (e.g. you shouldn't use it in an HTML + attribute or a `script` tag). + +Reading a dump +-------------- + +For simple variables, reading the output should be straightforward:: + + dump(array(true, 1.1, "string")); .. _Packagist: https://packagist.org/packages/symfony/var-dumper From cb0ee899f51df62e72063e54f833ea33dcd5637b Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Wed, 29 Oct 2014 20:30:04 +0100 Subject: [PATCH 09/14] =?UTF-8?q?=C2=A7=20about=20Data::getLimitedClone()?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/var_dumper/advanced.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst index c0b3dd9c953..70bf85e5198 100644 --- a/components/var_dumper/advanced.rst +++ b/components/var_dumper/advanced.rst @@ -27,6 +27,23 @@ Before cloning, you can configure the limits with:: They will be applied when calling ``->cloneVar()`` afterwards. +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 + limits 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 ~~~~~~~ From 6a3e17088332f9dc499aa765fe6877584893b4d3 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Thu, 30 Oct 2014 09:51:00 +0100 Subject: [PATCH 10/14] =?UTF-8?q?=C2=A7=20about=20DebugBundle=20config?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/var_dumper/advanced.rst | 7 ++-- components/var_dumper/introduction.rst | 56 +++++++++++++++++--------- 2 files changed, 42 insertions(+), 21 deletions(-) diff --git a/components/var_dumper/advanced.rst b/components/var_dumper/advanced.rst index 70bf85e5198..29aff0c31da 100644 --- a/components/var_dumper/advanced.rst +++ b/components/var_dumper/advanced.rst @@ -31,9 +31,10 @@ 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 + +- 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 limits can be changed back and forth before dumping since they do not affect diff --git a/components/var_dumper/introduction.rst b/components/var_dumper/introduction.rst index bd48be2809d..2c2ae679899 100644 --- a/components/var_dumper/introduction.rst +++ b/components/var_dumper/introduction.rst @@ -23,11 +23,8 @@ You can install the component in 2 different ways: The dump() function ------------------- -The VarDumper component creates a global ``dump()`` function that is -configured out of the box: HTML or CLI output is automatically selected based -on the current PHP SAPI. - -The advantages of this function are: +The VarDumper component creates a global ``dump()`` function that you can +use instead of e.g. :phpfunction:`var_dump`. By using it, you'll gain: - per object and resource types specialized view to e.g. filter out Doctrine internals while dumping a single proxy entity, or get more @@ -47,44 +44,67 @@ You can change the behavior of this function by calling :method:`VarDumper::setHandler($callable) `: calls to ``dump()`` will then be forwarded to ``$callable``. -Where does the output go? -------------------------- +Output format and destination +----------------------------- -If you read the advanced documentation, you'll learn how to change the -format or redirect the output to wherever you want. +If you read the `advanced documentation `, you'll learn how to +change the format or redirect the output to wherever you want. By default, these are selected based on your current PHP SAPI: -- on the command line (CLI SAPI), the output is written on `STDERR`. This +- on the command line (CLI SAPI), the output is written on ``STDERR``. This can be surprising to some because this bypasses PHP's output buffering - mechanism. On the other hand, this give the possibility to easily split + mechanism. On the other hand, it give the possibility to easily split dumps from regular output by using pipe redirection. - on other SAPIs, dumps are written as HTML on the regular output. DebugBundle and Twig integration -------------------------------- -The `DebugBundle` allows greater integration of the component into the +The ``DebugBundle`` allows greater integration of the component into the Symfony full stack framework. It is enabled by default in the dev environement of the standard edition since version 2.6. Since generating (even debug) output in the controller or in the model of your application may just break it by e.g. sending HTTP headers or -corrupting your view, the bundle configures the `dump()` function so that +corrupting your view, the bundle configures the ``dump()`` function so that variables are dumped in the web debug toolbar. -But if the toolbar can not be displayed because you e.g. called `die`/`exit` +But if the toolbar can not be displayed because you e.g. called ``die``/``exit`` or a fatal error occurred, then dumps are written on the regular output. In a Twig template, two constructs are available for dumping a variable. -Choosing between both is generally only a matter of personal taste: +Choosing between both is mostly a matter of personal taste, still: -- `{% dump foo.bar %}` is the way to go when the original template output +- ``{% dump foo.bar %}`` is the way to go when the original template output shall not be modified: variables are not dumped inline, but in the web debug toolbar. -- on the contrary, `{{ dump(foo.bar) }}` dumps inline and thus may or not +- on the contrary, ``{{ dump(foo.bar) }}`` dumps inline and thus may or not be suited to your use case (e.g. you shouldn't use it in an HTML - attribute or a `script` tag). + attribute or a ``