§ about DebugBundle config

symfony · weaverryan · Nov 5, 2014 · Sep 17, 2014 · Sep 30, 2014 · Sep 30, 2014
commit 6a3e17088332f9dc499aa765fe6877584893b4d3
diff --git 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
@@ -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) <Symfony\\Component\\VarDumper\\VarDumper::setHandler>`:
 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 <advanced>`, 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 ``<script>`` tag).
+
+By default for nested variables, dumps are limited to a subset of their
+original value. You can configure the limits in terms of:
+- maximum number of items to dump,
+- maximum string length before truncation.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        debug:
+           max_items: 250
+           max_string_length: -1
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/debug"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/debug http://symfony.com/schema/dic/debug/debug-1.0.xsd">
+
+            <config max-items="250" max-string-length="-1" />
+        </container>
 
 Reading a dump
 --------------