[Cookbook][Configuration] add configuration cookbook handlig parameters in Configurator class

cookbook/bundles/extension.rst

@@ -89,6 +89,11 @@ The second method has several specific advantages:
     supported configuration settings for which backward compatibility will
     be maintained.
 
+.. seealso::
+
+    For other usages of the parameter ``%`` syntax see
+    :doc:`Using Parameters Within A Dependency Injection Class </cookbook/using_parameters_in_dic>`.
+
 .. index::
    single: Bundle; Extension
    single: DependencyInjection; Extension

cookbook/configuration/apache_router.rst

@@ -1,5 +1,5 @@
 .. index::
-   single: Apache Router
+    single: Apache Router
 
 How to use the Apache Router
 ============================

cookbook/configuration/environments.rst

@@ -1,5 +1,5 @@
 .. index::
-   single: Environments
+    single: Environments
 
 How to Master and Create new Environments
 =========================================

cookbook/configuration/external_parameters.rst

@@ -1,5 +1,5 @@
 .. index::
-   single: Environments; External parameters
+    single: Environments; External parameters
 
 How to Set External Parameters in the Service Container
 =======================================================

cookbook/configuration/front_controllers_and_kernel.rst

@@ -1,6 +1,6 @@
 .. index::
-   single: How front controller, ``AppKernel`` and environments
-   work together
+    single: How front controller, ``AppKernel`` and environments
+    work together
 
 Understanding how the Front Controller, Kernel and Environments work together
 =============================================================================

cookbook/configuration/index.rst

@@ -6,6 +6,7 @@ Configuration
 
     environments
     override_dir_structure
+    using_parameters_in_dic
     front_controllers_and_kernel
     external_parameters
     pdo_session_storage

cookbook/configuration/override_dir_structure.rst

@@ -1,5 +1,5 @@
 .. index::
-   single: Override Symfony
+    single: Override Symfony
 
 How to override Symfony's Default Directory Structure
 =====================================================

cookbook/configuration/pdo_session_storage.rst

@@ -1,5 +1,5 @@
 .. index::
-   single: Session; Database Storage
+    single: Session; Database Storage
 
 How to use PdoSessionHandler to store Sessions in the Database
 ==============================================================

cookbook/configuration/using_parameters_in_dic.rst

@@ -0,0 +1,159 @@
+.. index::
+    single: Using Parameters Within A Dependency Injection Class
+
+Using Parameters Within A Dependency Injection Class
+----------------------------------------------------
+
+You have seen how to use configuration parameters within
+:ref:`Symfony service container <book-service-container-parameters>`.
+There are special cases such as when you want, for instance, to use the
+``%kernel.debug%`` parameter to make the services in your bundle enter
+debug mode. For this case there is more work to do in order
+to make the system understand the parameter value. By default
+your parameter ``%kernel.debug%`` will be treated as a
+simple string. Consider this example with the AcmeDemoBundle::
+
+    // Inside Configuration class
+    $rootNode
+        ->children()
+            ->booleanNode('logging')->defaultValue('%kernel.debug%')->end()
+            // ...
+        ->end()
+    ;
+
+    // Inside the Extension class
+    $config = $this->processConfiguration($configuration, $configs);
+    var_dump($config['logging']);
+
+Now, examine the results to see this closely:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        my_bundle:
+            logging: true
+            # true, as expected
+
+        my_bundle:
+            logging: %kernel.debug%
+            # true/false (depends on 2nd parameter of AppKernel),
+            # as expected, because %kernel.debug% inside configuration
+            # gets evaluated before being passed to the extension
+
+        my_bundle: ~
+        # passes the string "%kernel.debug%".
+        # Which is always considered as true.
+        # The Configurator does not know anything about
+        # "%kernel.debug%" being a parameter.
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            my-bundle="http://example.org/schema/dic/my_bundle">
+
+            <my-bundle:config logging="true" />
+            <!-- true, as expected -->
+
+             <my-bundle:config logging="%kernel.debug%" />
+             <!-- true/false (depends on 2nd parameter of AppKernel),
+                  as expected, because %kernel.debug% inside configuration
+                  gets evaluated before being passed to the extension -->
+
+            <my-bundle:config />
+            <!-- passes the string "%kernel.debug%".
+                 Which is always considered as true.
+                 The Configurator does not know anything about
+                 "%kernel.debug%" being a parameter. -->
+        </container>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('my_bundle', array(
+                'logging' => true,
+                // true, as expected
+            )
+        );
+
+        $container->loadFromExtension('my_bundle', array(
+                'logging' => "%kernel.debug%",
+                // true/false (depends on 2nd parameter of AppKernel),
+                // as expected, because %kernel.debug% inside configuration
+                // gets evaluated before being passed to the extension
+            )
+        );
+
+        $container->loadFromExtension('my_bundle');
+        // passes the string "%kernel.debug%".
+        // Which is always considered as true.
+        // The Configurator does not know anything about
+        // "%kernel.debug%" being a parameter.
+
+In order to support this use case, the ``Configuration`` class has to
+be injected with this parameter via the extension as follows::
+
+    namespace Acme\DemoBundle\DependencyInjection;
+
+    use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+    use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+    use Symfony\Component\Config\Definition\ConfigurationInterface;
+
+    class Configuration implements ConfigurationInterface
+    {
+        private $debug;
+
+        public function  __construct($debug)
+        {
+            $this->debug = (Boolean) $debug;
+        }
+
+        public function getConfigTreeBuilder()
+        {
+            $treeBuilder = new TreeBuilder();
+            $rootNode = $treeBuilder->root('acme_demo');
+
+            $rootNode
+                ->children()
+                    // ...
+                    ->booleanNode('logging')->defaultValue($this->debug)->end()
+                    // ...
+                ->end()
+            ;
+
+            return $treeBuilder;
+        }
+    }
+
+And set it in the constructor of ``Configuration`` via the ``Extension`` class::
+
+    namespace Acme\DemoBundle\DependencyInjection;
+
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+    use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+    use Symfony\Component\Config\FileLocator;
+
+    class AcmeDemoExtension extends Extension
+    {
+        // ...
+
+        public function getConfiguration(array $config, ContainerBuilder $container)
+        {
+            return new Configuration($container->getParameter('kernel.debug'));
+        }
+    }
+
+.. sidebar:: Setting the Default in the Extension
+
+There are some instances of ``%kernel.debug%`` usage within a ``Configurator``
+class in TwigBundle and AsseticBundle, however this is because the default
+parameter value is set by the Extension class. For example in AsseticBundle,
+you can find::
+
+    $container->setParameter('assetic.debug', $config['debug']);
+
+The string ``%kernel.debug%`` passed here as an argument handles the
+interpreting job to the container which in turn does the evaluation.
+Both ways accomplish similar goals. AsseticBundle will not use
+anymore ``%kernel.debug%`` but rather the new ``%assetic.debug%`` parameter.

cookbook/configuration/web_server_configuration.rst

@@ -1,5 +1,5 @@
 .. index::
-   single: Web Server
+    single: Web Server
 
 Configuring a web server
 ========================

cookbook/map.rst.inc

@@ -24,6 +24,7 @@
 
   * :doc:`/cookbook/configuration/environments`
   * :doc:`/cookbook/configuration/override_dir_structure`
+  * :doc:`/cookbook/configuration/using_parameters_in_dic`
   * :doc:`/cookbook/configuration/front_controllers_and_kernel`
   * :doc:`/cookbook/configuration/external_parameters`
   * :doc:`/cookbook/configuration/pdo_session_storage`

cookbook/routing/service_container_parameters.rst

@@ -120,3 +120,8 @@ path):
     However, as the ``%`` characters included in any URL are automatically encoded,
     the resulting URL of this example would be ``/score-50%25`` (``%25`` is the
     result of encoding the ``%`` character).
+
+.. seealso::
+
+    For other usages of the parameter ``%`` syntax see
+    :doc:`Using Parameters Within A Dependency Injection Class </cookbook/using_parameters_in_dic>`.