feature #7217 Document new environment variables and display options (sawmurai, javiereguiluz, Fabian Becker)

This PR was merged into the 3.2 branch.

Discussion
----------

Document new environment variables and display options

Pull request for ticket #7177

Commits
-------

29080a6 Minor formatting changes
2ef1b60 Fix format
0c46fce Respect 80 chars line length
6b2248e Fix mention of file
ad90321 Describe flags in more detail
dfb6d6a Trimmed some lines to respect the 80-char soft limit
9340846 Replaced the list to use an unordered list
adbec6d Reformat documentation and link to class doc.
7b26e44 Document new environment variables and display options

Author: xabbuh

components/var_dumper/advanced.rst

@@ -181,6 +181,94 @@ method. They also typically implement the
 them from re-implementing the logic required to walk through a
 :class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object's internal structure.
 
+The :class:`Symfony\\Component\\VarDumper\\Dumper\\HtmlDumper` limits string
+length and nesting depth of the output to make it more readable. These options
+can be overriden by the third optional parameter of the
+:method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`
+method::
+
+    use Symfony\Component\VarDumper\Dumper\HtmlDumper;
+
+    $output = fopen('php://memory', 'r+b');
+
+    $dumper = new HtmlDumper();
+    $dumper->dump($var, $output, array(
+        // 1 and 160 are the default values for these options
+        'maxDepth' => 1,
+        'maxStringLength' => 160
+    ));
+
+The output format of a dumper can be fine tuned by the two flags 
+``DUMP_STRING_LENGTH`` and ``DUMP_LIGHT_ARRAY`` which are passed as a bitmap
+in the third constructor argument. They can also be set via environment 
+variables when using
+:method:`assertDumpEquals($dump, $data, $message) <Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpEquals>`
+during unit testing.
+
+If ``DUMP_STRING_LENGTH`` is set, then the length of a string is displayed
+next to its content:
+
+.. code-block:: php
+
+    use Symfony\Component\VarDumper\Dumper\AbstractDumper;
+    use Symfony\Component\VarDumper\Dumper\CliDumper;
+
+    $var = array('test');
+    $dumper = new CliDumper();
+    echo $dumper->dump($var, true);
+
+    // array:1 [
+    //   0 => "test"
+    // ]
+
+    $dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH);
+    echo $dumper->dump($var, true);
+
+    // (added string length before the string)
+    // array:1 [
+    //   0 => (4) "test"
+    // ]
+
+If ``DUMP_LIGHT_ARRAY`` is set, then arrays are dumped in a shortened format
+similar to PHP's short array notation:
+
+.. code-block:: php
+
+    use Symfony\Component\VarDumper\Dumper\AbstractDumper;
+    use Symfony\Component\VarDumper\Dumper\CliDumper;
+
+    $var = array('test');
+    $dumper = new CliDumper();
+    echo $dumper->dump($var, true);
+
+    // array:1 [
+    //   0 => "test"
+    // ]
+
+    $dumper = new CliDumper(null, null, AbstractDumper::DUMP_LIGHT_ARRAY);
+    echo $dumper->dump($var, true);
+
+    // (no more array:1 prefix)
+    // [
+    //   0 => "test"
+    // ]
+
+If you would like to use both options, then you can just    combine them by
+using a the logical OR operator ``|``:
+
+.. code-block:: php
+
+    use Symfony\Component\VarDumper\Dumper\AbstractDumper;
+    use Symfony\Component\VarDumper\Dumper\CliDumper;
+
+    $var = array('test');
+    $dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH | AbstractDumper::DUMP_LIGHT_ARRAY);
+    echo $dumper->dump($var, true);
+
+    // [
+    //   0 => (4) "test"
+    // ]
+
 Casters
 -------