Document new environment variables and display options

components/var_dumper/advanced.rst

@@ -181,6 +181,95 @@ 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. These options can be overriden by
+providing a third parameter when calling 
+:method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`
+::
+
+    use Symfony\Component\VarDumper\Dumper\HtmlDumper;
+
+    $output = fopen('php://memory', 'r+b');
+
+    $dumper = new HtmlDumper();
+    $dumper->dump($var, $output, array(
+        'maxDepth' => 1,
+        'maxStringLength' => 160
+    ));
+
+    // Limit nesting to 1 level and string length to 160 characters (default)
+
+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. The flags can be configured in the PHPUnit configuration.
+
+* 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
 -------