From 5b749b84c3e5a9e1ab9a5e88c883548ab85621d3 Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Thu, 30 Jul 2015 18:27:30 +0200
Subject: [PATCH] Add DebugBundle config reference

---
 components/var_dumper/introduction.rst | 51 +++--------------
 reference/configuration/debug.rst      | 76 ++++++++++++++++++++++++++
 reference/index.rst                    |  1 +
 reference/map.rst.inc                  |  1 +
 4 files changed, 87 insertions(+), 42 deletions(-)
 create mode 100644 reference/configuration/debug.rst

diff --git a/components/var_dumper/introduction.rst b/components/var_dumper/introduction.rst
index 086695c471c..e4875649516 100644
--- a/components/var_dumper/introduction.rst
+++ b/components/var_dumper/introduction.rst
@@ -42,8 +42,9 @@ use instead of e.g. :phpfunction:`var_dump`. By using it, you'll gain:
 For example::
 
     require __DIR__.'/vendor/autoload.php';
+
     // create a variable, which could be anything!
-    $someVar = '...';
+    $someVar = ...;
 
     dump($someVar);
 
@@ -70,14 +71,14 @@ current PHP SAPI:
     #. Run ``composer global require symfony/var-dumper``;
     #. Add ``auto_prepend_file = ${HOME}/.composer/vendor/autoload.php``
        to your ``php.ini`` file;
-    #. From time to time, run ``composer global update`` to have the latest
-       bug fixes.
+    #. From time to time, run ``composer global update symfony/var-dumper``
+       to have the latest bug fixes.
 
 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* and *test*
+The DebugBundle allows greater integration of the component into the Symfony
+full-stack framework. It is enabled by default in the *dev* and *test*
 environment of the standard edition since version 2.6.
 
 Since generating (even debug) output in the controller or in the model
@@ -98,43 +99,9 @@ Choosing between both is mostly a matter of personal taste, still:
   be suited to your use case (e.g. you shouldn't use it in an HTML
   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.
-
-Since dumping into the toolbar is not always possible - e.g. when working on a
-JSON API - you can have an alternate output destination for dumps. This is
-configurable with the ``debug.dump_destination`` option, that you can typically
-set to ``php://stderr``.
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        debug:
-           max_items: 250
-           max_string_length: -1
-           dump_destination: ~
-
-    .. 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" dump-destination="null" />
-        </container>
-
-    .. code-block:: php
-
-        $container->loadFromExtension('debug', array(
-           'max_items' => 250,
-           'max_string_length' => -1,
-           'dump_destination' => null,
-        ));
+This behaviour can be changed by configuring the ``dump.dump_destination``
+option. Read more about this and other options in
+:doc:`the DebugBundle configuration reference </reference/configuration/debug>`.
 
 Dump Examples and Output
 ------------------------
diff --git a/reference/configuration/debug.rst b/reference/configuration/debug.rst
new file mode 100644
index 00000000000..7e9f9708f04
--- /dev/null
+++ b/reference/configuration/debug.rst
@@ -0,0 +1,76 @@
+.. index::
+    single: Configuration reference; Framework
+
+DebugBundle Configuration ("debug")
+===================================
+
+The DebugBundle allows greater integration of the
+:doc:`VarDumper component </components/var_dumper/introduction>` in the
+Symfony full-stack framework and can be configured under the ``debug`` key
+in your application configuration. When using XML, you must use the
+``http://symfony.com/schema/dic/debug`` namespace.
+
+.. versionadded::
+    The DebugBundle was introduced in Symfony 2.6.
+
+.. tip::
+
+   The XSD schema is available at
+   ``http://symfony.com/schema/dic/debug/debug-1.0.xsd``.
+
+Configuration
+-------------
+
+* `max_items`_
+* `max_string_length`_ 
+* `dump_destination`_
+
+max_items
+~~~~~~~~~
+
+**type**: ``integer`` **default**: ``2500``
+
+This is the maximum number of items to dump. Setting this option to ``-1``
+disables the limit.
+
+max_string_length
+~~~~~~~~~~~~~~~~~
+
+**type**: ``integer`` **default**: ``-1``
+
+This option configures the maximum string length before truncating the
+string. The default value (``-1``) means that strings are never truncated.
+
+dump_destination
+~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+Configures the output destination of the dumps.
+
+By default, the dumps are shown in the toolbar. Since this is not always
+possible (e.g. when working on a JSON API), you can have an alternate output
+destination for dumps. Typically, you would set this to ``php://stderr``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        debug:
+           dump_destination: php://stderr
+
+    .. 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 dump-destination="php://stderr" />
+        </container>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('debug', array(
+           'dump_destination' => 'php://stderr',
+        ));
diff --git a/reference/index.rst b/reference/index.rst
index 9d07c4c4609..8dcd0ae955e 100644
--- a/reference/index.rst
+++ b/reference/index.rst
@@ -12,6 +12,7 @@ Reference Documents
     configuration/twig
     configuration/monolog
     configuration/web_profiler
+    configuration/debug
 
     configuration/kernel
 
diff --git a/reference/map.rst.inc b/reference/map.rst.inc
index 174cdd908cc..1d322527c61 100644
--- a/reference/map.rst.inc
+++ b/reference/map.rst.inc
@@ -13,6 +13,7 @@
   * :doc:`twig </reference/configuration/twig>`
   * :doc:`monolog </reference/configuration/monolog>`
   * :doc:`web_profiler </reference/configuration/web_profiler>`
+  * :doc:`debug </reference/configuration/debug>` (new in 2.6)
 
 * :doc:`Configuring the Kernel (e.g. AppKernel) </reference/configuration/kernel>`