From 036edcbcdcf9c6b48cc9c30dcff12377707874c6 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Wed, 1 Oct 2014 09:48:39 +0200 Subject: [PATCH] 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