[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 Configuration Parameters </cookbook/using_configuration_parameters>`.
+
 .. 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_configuration_parameters
     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_configuration_parameters.rst

@@ -0,0 +1,217 @@
+.. index::
+    single: Using Configuration Parameters
+
+Using Configuration Parameters
+==============================
+
+Parameters, such as ``kernel.root_dir`` (pointing to a path) or ``kernel.debug``
+(whether debug mode is enabled), are common in configuration. By wrapping the
+parameter name within 2 ``%`` characters, you indicate that this value should
+be replaced by the value of the parameter. When using Symfony, you can have
+parameters defined in a bundle and used only in that bundle and also parameters
+defined in a bundle and used in another. Usually they would have a name
+like ``demo_bundle.service_doer.local_parameter`` making explicit where this
+parameter comes from. If the parameter is global then it may not have a
+namespace, e.g. ``%some_global_option_here%``.
+
+Basic Usage
+-----------
+
+You can use parameters inside the ``parameters.yml`` file:
+
+.. code-block:: yaml
+
+    # app/config/parameters.yml
+    parameters:
+        payment_test_mode: "%kernel.root_dir%"
+
+Inside ``config.yml`` and other configuration files building larger
+strings:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        my_bundle:
+            local:
+                directory:  "%kernel.root_dir%/../web/media/image"
+
+    .. 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>
+                <my-bundle:local directory="%kernel.root_dir%/../web/media/image" />
+            </my-bundle:config>
+        </container>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('my_bundle', array(
+            'local' => array(
+                'directory' => '%kernel.root_dir%/../web/media/image',
+            ),
+        ));
+
+For more information on how parameters are used in Symfony please see
+:ref:`parameters <book-service-container-parameters>`.
+
+Besides these usages above you can use this syntax in routing files and handle
+parameters in special cases as discussed below.
+
+Using Parameters in your Bundle Configuration
+---------------------------------------------
+
+If for instance, there is a use case in which you want to use the
+``%kernel.debug%`` debug mode parameter to make your bundle adapt its
+configuration depending on this. For this case you cannot use
+the syntax directly and expect this to work. The configuration handling
+will just treat this ``%kernel.debug%`` as a 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/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 Configuration Parameters </cookbook/using_configuration_parameters>`.