feature #3420 [Cookbook][Configuration] add configuration cookbook ha…

…ndlig parameters in Configurator class (cordoval) This PR was merged into the 2.3 branch. Discussion ---------- [Cookbook][Configuration] add configuration cookbook handlig parameters in Configurator class | Q | A | | --- | --- | | Doc fix? | yes | | New docs? | no | | Applies to | 2.3+ | | Fixed tickets | #3219 | | License | CC-ASA 3.0 Unported | Sent using [Gush](https://github.com/cordoval/gush) Commits ------- 9710bb5 final touches ad27a83 address comments by xabbuh a6bda5e address weaverryan comments 28c144a plug xml and php version of the configuration c07c655 fix see also block ec13feb plug changes according to comments 243c0d1 create configuration cookbook with ways of handling paramters in Configurator class
symfony · Mar 18, 2014 · 5965ec8 · 5965ec8
2 parents a1050eb + 9710bb5
commit 5965ec8
Show file tree

Hide file tree

Showing 12 changed files with 179 additions and 8 deletions.
diff --git a/cookbook/bundles/extension.rst b/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 parameter handling within a Dependency Injection class see
+    :doc:`</cookbook/configuration/using_parameters_in_dic>`.
+
 .. index::
    single: Bundle; Extension
    single: DependencyInjection; Extension

diff --git a/cookbook/configuration/apache_router.rst b/cookbook/configuration/apache_router.rst
@@ -1,5 +1,5 @@
 .. index::
-   single: Apache Router
+    single: Apache Router
 
 How to use the Apache Router
 ============================

diff --git a/cookbook/configuration/environments.rst b/cookbook/configuration/environments.rst
@@ -1,5 +1,5 @@
 .. index::
-   single: Environments
+    single: Environments
 
 How to Master and Create new Environments
 =========================================

diff --git a/cookbook/configuration/external_parameters.rst b/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
 =======================================================

diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst
@@ -1,6 +1,6 @@
 .. index::
-   single: How front controller, ``AppKernel`` and environments
-   work together
+    single: How the front controller, ``AppKernel`` and environments
+    work together
 
 Understanding how the Front Controller, Kernel and Environments work together
 =============================================================================

diff --git a/cookbook/configuration/index.rst b/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

diff --git a/cookbook/configuration/override_dir_structure.rst b/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
 =====================================================

diff --git a/cookbook/configuration/pdo_session_storage.rst b/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
 ==============================================================

diff --git a/cookbook/configuration/using_parameters_in_dic.rst b/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 containers <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"
+            xmlns: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.
diff --git a/cookbook/configuration/web_server_configuration.rst b/cookbook/configuration/web_server_configuration.rst
@@ -1,5 +1,5 @@
 .. index::
-   single: Web Server
+    single: Web Server
 
 Configuring a web server
 ========================

diff --git a/cookbook/map.rst.inc b/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`

diff --git a/cookbook/routing/service_container_parameters.rst b/cookbook/routing/service_container_parameters.rst
@@ -124,3 +124,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 parameter handling within a Dependency Injection class see
+    :doc:`</cookbook/configuration/using_parameters_in_dic>`.