Add DebugBundle config reference

Author: wouterj

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,29 +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.
-
-.. 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>
+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>`.
 
 Using the VarDumper Component in your PHPUnit Test Suite
 --------------------------------------------------------

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',
+        ));

reference/index.rst

@@ -12,6 +12,7 @@ Reference Documents
     configuration/twig
     configuration/monolog
     configuration/web_profiler
+    configuration/debug
 
     configuration/kernel
 

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>`