diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index 0157664e531..7d2c05dabf0 100644 --- 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:``. + .. index:: single: Bundle; Extension single: DependencyInjection; Extension diff --git a/cookbook/configuration/apache_router.rst b/cookbook/configuration/apache_router.rst index c740979534a..db01c1fad38 100644 --- 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 index 1ea6f578ccd..900851ff982 100644 --- 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 index b2fb61bce5f..f177f392f1f 100644 --- 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 index c49788f9056..1acea0b2a75 100644 --- 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 index c3850724c88..69250747457 100644 --- 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 index 31aeb973847..41e2e2ab000 100644 --- 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 index 7e811d205f7..bd6506f51c9 100644 --- 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 new file mode 100644 index 00000000000..c2d869cfa7a --- /dev/null +++ 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 `. +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 + + + + + + + + + + + + + + + .. 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 index 306a99b644e..647cb5c0d01 100644 --- 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 index b2777f42f5e..321d302949e 100644 --- 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 index 8eaa7d524f8..de88cee0256 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/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 parameter handling within a Dependency Injection class see + :doc:``. \ No newline at end of file