From 243c0d1b2d60b04033ec16ea7e8f7b0d2b6b5f7d Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Sat, 4 Jan 2014 12:04:27 -0500 Subject: [PATCH 1/7] create configuration cookbook with ways of handling paramters in Configurator class --- cookbook/bundles/extension.rst | 2 + cookbook/configuration.rst | 182 ++++++++++++++++++ cookbook/index.rst | 1 + .../routing/service_container_parameters.rst | 2 + 4 files changed, 187 insertions(+) create mode 100644 cookbook/configuration.rst diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index 0157664e531..13d983c7f28 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -89,6 +89,8 @@ The second method has several specific advantages: supported configuration settings for which backward compatibility will be maintained. +For other usages of the parameter ``%`` syntax see :doc:`Configuration `. + .. index:: single: Bundle; Extension single: DependencyInjection; Extension diff --git a/cookbook/configuration.rst b/cookbook/configuration.rst new file mode 100644 index 00000000000..c5ee472c42d --- /dev/null +++ b/cookbook/configuration.rst @@ -0,0 +1,182 @@ +.. index:: +single: Configuration + +Configuration Usages +==================== + +Parameters are common in configuration such as ``%kernel.root_dir%`` +(which is used for passing a path) or ``%kernel.debug%`` (which is used for +passing a boolean indicating if mode is debug). The syntax wrapping an +alias string with ``%`` conveys that this is a value defined as a parameter +and will be evaluated somewhere down the line and used. Within Symfony +we 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 namespace 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%``. + +We can have parameters being used inside ``parameters.yml``: + +.. configuration-block:: + + .. 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 + +We can also use parameters in service configuration files: + +.. configuration-block:: + + .. code-block:: xml + + + + + + + + + +For more information on how parameters are used in Symfony please see +:ref:`parameters `. + +Besides these usages above we can use this syntax in routing files and handle +parameters in special cases as discussed below. + +If for instance, there is a use case in which we want to use the +``%kernel.debug%`` debug mode parameter to make our bundle adapt its +configuration depending on this. For this case we cannot use +the syntax directly and expect this to work. The configuration handling +will just tread this ``%kernel.debug%`` as a string. Let's consider +this example with ``AcmeDemoBundle``: + +.. code-block:: php + + // Inside Configuration class + ->booleanNode('logging')->defaultValue('%kernel.debug%')->end() + + // Inside the Extension class + $config = $this->processConfiguration($configuration, $configs); + var_dump($config['logging']); + +Now let's examine the results to see this closely: + +.. configuration-block:: + + .. code-block:: xml + + 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. + # Configurator class does not know anything about the default + # string ``%kernel.debug%``. + +In order to support this use case ``Configuration`` class has to +be injected with this parameter via the extension as follows: + +.. code-block:: php + + debug = (Boolean) $debug; + } + + /** + * {@inheritDoc} + */ + public function getConfigTreeBuilder() + { + $treeBuilder = new TreeBuilder(); + $rootNode = $treeBuilder->root('acme_demo'); + + $rootNode + // ... + ->booleanNode('logging')->defaultValue($this->debug)->end() + // ... + ; + + return $treeBuilder; + } + } + +And set it in the constructor of ``Configuration`` via the Extension class: + +.. code-block:: php + + getParameter('kernel.debug')); + } + } + +There are some instances of ``%kernel.debug%`` usage within a ``Configurator`` +class in ``TwigBundle`` and ``AsseticBundle``, however this is because they are +setting the parameter value in the container via the Extension class. For +example in ``AsseticBundle`` we have: + +.. code-block:: php + + $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/index.rst b/cookbook/index.rst index 07869cad14a..b3c546711c3 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -7,6 +7,7 @@ The Cookbook assetic/index bundles/index cache/index + configuration configuration/index console/index controller/index diff --git a/cookbook/routing/service_container_parameters.rst b/cookbook/routing/service_container_parameters.rst index 8eaa7d524f8..819f88aa0a1 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/cookbook/routing/service_container_parameters.rst @@ -120,3 +120,5 @@ 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). + +For other usages of the parameter ``%`` syntax see :doc:`Configuration `. \ No newline at end of file From ec13febd17804e48a70b452be951908e1878723e Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Sat, 4 Jan 2014 21:32:22 -0500 Subject: [PATCH 2/7] plug changes according to comments --- cookbook/bundles/extension.rst | 5 +- cookbook/configuration.rst | 182 ------------------ cookbook/configuration/apache_router.rst | 2 +- cookbook/configuration/environments.rst | 2 +- .../configuration/external_parameters.rst | 2 +- .../front_controllers_and_kernel.rst | 4 +- cookbook/configuration/index.rst | 1 + .../configuration/override_dir_structure.rst | 2 +- .../configuration/pdo_session_storage.rst | 2 +- .../using_configuration_parameters.rst | 177 +++++++++++++++++ .../web_server_configuration.rst | 2 +- cookbook/index.rst | 1 - 12 files changed, 190 insertions(+), 192 deletions(-) delete mode 100644 cookbook/configuration.rst create mode 100644 cookbook/configuration/using_configuration_parameters.rst diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index 13d983c7f28..2d9d3051f66 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -89,7 +89,10 @@ The second method has several specific advantages: supported configuration settings for which backward compatibility will be maintained. -For other usages of the parameter ``%`` syntax see :doc:`Configuration `. +.. seealso:: + + For other usages of the parameter ``%`` syntax see + :doc:`Using Configuration Parameters `. .. index:: single: Bundle; Extension diff --git a/cookbook/configuration.rst b/cookbook/configuration.rst deleted file mode 100644 index c5ee472c42d..00000000000 --- a/cookbook/configuration.rst +++ /dev/null @@ -1,182 +0,0 @@ -.. index:: -single: Configuration - -Configuration Usages -==================== - -Parameters are common in configuration such as ``%kernel.root_dir%`` -(which is used for passing a path) or ``%kernel.debug%`` (which is used for -passing a boolean indicating if mode is debug). The syntax wrapping an -alias string with ``%`` conveys that this is a value defined as a parameter -and will be evaluated somewhere down the line and used. Within Symfony -we 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 namespace 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%``. - -We can have parameters being used inside ``parameters.yml``: - -.. configuration-block:: - - .. 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 - -We can also use parameters in service configuration files: - -.. configuration-block:: - - .. code-block:: xml - - - - - - - - - -For more information on how parameters are used in Symfony please see -:ref:`parameters `. - -Besides these usages above we can use this syntax in routing files and handle -parameters in special cases as discussed below. - -If for instance, there is a use case in which we want to use the -``%kernel.debug%`` debug mode parameter to make our bundle adapt its -configuration depending on this. For this case we cannot use -the syntax directly and expect this to work. The configuration handling -will just tread this ``%kernel.debug%`` as a string. Let's consider -this example with ``AcmeDemoBundle``: - -.. code-block:: php - - // Inside Configuration class - ->booleanNode('logging')->defaultValue('%kernel.debug%')->end() - - // Inside the Extension class - $config = $this->processConfiguration($configuration, $configs); - var_dump($config['logging']); - -Now let's examine the results to see this closely: - -.. configuration-block:: - - .. code-block:: xml - - 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. - # Configurator class does not know anything about the default - # string ``%kernel.debug%``. - -In order to support this use case ``Configuration`` class has to -be injected with this parameter via the extension as follows: - -.. code-block:: php - - debug = (Boolean) $debug; - } - - /** - * {@inheritDoc} - */ - public function getConfigTreeBuilder() - { - $treeBuilder = new TreeBuilder(); - $rootNode = $treeBuilder->root('acme_demo'); - - $rootNode - // ... - ->booleanNode('logging')->defaultValue($this->debug)->end() - // ... - ; - - return $treeBuilder; - } - } - -And set it in the constructor of ``Configuration`` via the Extension class: - -.. code-block:: php - - getParameter('kernel.debug')); - } - } - -There are some instances of ``%kernel.debug%`` usage within a ``Configurator`` -class in ``TwigBundle`` and ``AsseticBundle``, however this is because they are -setting the parameter value in the container via the Extension class. For -example in ``AsseticBundle`` we have: - -.. code-block:: php - - $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/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..64b1a282899 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 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..3205a8d0a3e 100644 --- a/cookbook/configuration/index.rst +++ b/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 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_configuration_parameters.rst b/cookbook/configuration/using_configuration_parameters.rst new file mode 100644 index 00000000000..98e4890fb99 --- /dev/null +++ b/cookbook/configuration/using_configuration_parameters.rst @@ -0,0 +1,177 @@ +.. 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 + + + + + + + + + .. 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 `. + +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 tread this ``%kernel.debug%`` as a string. Consider +this example with the AcmeDemoBundle:: + + // Inside Configuration class + ->booleanNode('logging')->defaultValue('%kernel.debug%')->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 + + I confess i need help here @WouterJ + + .. code-block:: php + + I confess i need help here @WouterJ + +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/index.rst b/cookbook/index.rst index b3c546711c3..07869cad14a 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -7,7 +7,6 @@ The Cookbook assetic/index bundles/index cache/index - configuration configuration/index console/index controller/index From c07c6554394af9ae2ea284dbd14485641e1c5bf6 Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Sat, 4 Jan 2014 21:36:07 -0500 Subject: [PATCH 3/7] fix see also block --- cookbook/routing/service_container_parameters.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/cookbook/routing/service_container_parameters.rst b/cookbook/routing/service_container_parameters.rst index 819f88aa0a1..5d1f4b48117 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/cookbook/routing/service_container_parameters.rst @@ -121,4 +121,7 @@ path): the resulting URL of this example would be ``/score-50%25`` (``%25`` is the result of encoding the ``%`` character). -For other usages of the parameter ``%`` syntax see :doc:`Configuration `. \ No newline at end of file +.. seealso:: + + For other usages of the parameter ``%`` syntax see + :doc:`Using Configuration Parameters `. \ No newline at end of file From 28c144a4f4d6d67956a37aca401a905ed0917563 Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Sun, 5 Jan 2014 23:43:01 -0500 Subject: [PATCH 4/7] plug xml and php version of the configuration --- .../using_configuration_parameters.rst | 48 +++++++++++++++++-- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/cookbook/configuration/using_configuration_parameters.rst b/cookbook/configuration/using_configuration_parameters.rst index 98e4890fb99..a9ab84beae6 100644 --- a/cookbook/configuration/using_configuration_parameters.rst +++ b/cookbook/configuration/using_configuration_parameters.rst @@ -68,11 +68,16 @@ 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 tread this ``%kernel.debug%`` as a string. Consider +will just treat this ``%kernel.debug%`` as a string. Consider this example with the AcmeDemoBundle:: // Inside Configuration class - ->booleanNode('logging')->defaultValue('%kernel.debug%')->end() + $rootNode + ->children() + ->booleanNode('logging')->defaultValue('%kernel.debug%')->end() + // ... + ->end() + ; // Inside the Extension class $config = $this->processConfiguration($configuration, $configs); @@ -102,11 +107,46 @@ Now, examine the results to see this closely: .. code-block:: xml - I confess i need help here @WouterJ + + + + + + + + + + + + .. code-block:: php - I confess i need help here @WouterJ + $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:: From a6bda5e6a17a80dae5e90fc4d526e6082a55108b Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Fri, 10 Jan 2014 16:10:13 -0500 Subject: [PATCH 5/7] address weaverryan comments --- cookbook/bundles/extension.rst | 2 +- cookbook/configuration/index.rst | 2 +- ...meters.rst => using_parameters_in_dic.rst} | 84 +++---------------- cookbook/map.rst.inc | 1 + .../routing/service_container_parameters.rst | 2 +- 5 files changed, 17 insertions(+), 74 deletions(-) rename cookbook/configuration/{using_configuration_parameters.rst => using_parameters_in_dic.rst} (66%) diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index 2d9d3051f66..3cb43fe0943 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -92,7 +92,7 @@ The second method has several specific advantages: .. seealso:: For other usages of the parameter ``%`` syntax see - :doc:`Using Configuration Parameters `. + :doc:`Using Parameters Within A Dependency Injection Class `. .. index:: single: Bundle; Extension diff --git a/cookbook/configuration/index.rst b/cookbook/configuration/index.rst index 3205a8d0a3e..69250747457 100644 --- a/cookbook/configuration/index.rst +++ b/cookbook/configuration/index.rst @@ -6,7 +6,7 @@ Configuration environments override_dir_structure - using_configuration_parameters + using_parameters_in_dic front_controllers_and_kernel external_parameters pdo_session_storage diff --git a/cookbook/configuration/using_configuration_parameters.rst b/cookbook/configuration/using_parameters_in_dic.rst similarity index 66% rename from cookbook/configuration/using_configuration_parameters.rst rename to cookbook/configuration/using_parameters_in_dic.rst index a9ab84beae6..aa415728825 100644 --- a/cookbook/configuration/using_configuration_parameters.rst +++ b/cookbook/configuration/using_parameters_in_dic.rst @@ -1,75 +1,17 @@ .. 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 - - - - - - - - - .. 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 `. - -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:: + 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 `. +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 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 5d1f4b48117..ea35f4d3237 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/cookbook/routing/service_container_parameters.rst @@ -124,4 +124,4 @@ path): .. seealso:: For other usages of the parameter ``%`` syntax see - :doc:`Using Configuration Parameters `. \ No newline at end of file + :doc:`Using Parameters Within A Dependency Injection Class `. \ No newline at end of file From ad27a83d5a01bc379c38945fe9b1ccaaa875e999 Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Fri, 10 Jan 2014 18:05:58 -0500 Subject: [PATCH 6/7] address comments by xabbuh --- cookbook/bundles/extension.rst | 2 +- .../front_controllers_and_kernel.rst | 2 +- .../configuration/using_parameters_in_dic.rst | 24 +++++++++---------- .../routing/service_container_parameters.rst | 2 +- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index 3cb43fe0943..3abe0fbfb5f 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -92,7 +92,7 @@ The second method has several specific advantages: .. seealso:: For other usages of the parameter ``%`` syntax see - :doc:`Using Parameters Within A Dependency Injection Class `. + :doc:``. .. index:: single: Bundle; Extension diff --git a/cookbook/configuration/front_controllers_and_kernel.rst b/cookbook/configuration/front_controllers_and_kernel.rst index 64b1a282899..1acea0b2a75 100644 --- a/cookbook/configuration/front_controllers_and_kernel.rst +++ b/cookbook/configuration/front_controllers_and_kernel.rst @@ -1,5 +1,5 @@ .. index:: - single: How front controller, ``AppKernel`` and environments + 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/using_parameters_in_dic.rst b/cookbook/configuration/using_parameters_in_dic.rst index aa415728825..72ff3be36e9 100644 --- a/cookbook/configuration/using_parameters_in_dic.rst +++ b/cookbook/configuration/using_parameters_in_dic.rst @@ -1,11 +1,11 @@ .. index:: - single: Using Parameters Within A Dependency Injection Class + single: Using Parameters within a Dependency Injection Class -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 `. +: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 @@ -146,14 +146,14 @@ And set it in the constructor of ``Configuration`` via the ``Extension`` class:: .. 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:: + 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']); + $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. + 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/routing/service_container_parameters.rst b/cookbook/routing/service_container_parameters.rst index ea35f4d3237..b17a03df5b7 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/cookbook/routing/service_container_parameters.rst @@ -124,4 +124,4 @@ path): .. seealso:: For other usages of the parameter ``%`` syntax see - :doc:`Using Parameters Within A Dependency Injection Class `. \ No newline at end of file + :doc:``. \ No newline at end of file From 9710bb5184709f37ebf64b1a5b741af08228e4ee Mon Sep 17 00:00:00 2001 From: Luis Cordova Date: Sat, 11 Jan 2014 05:26:33 -0500 Subject: [PATCH 7/7] final touches --- cookbook/bundles/extension.rst | 2 +- cookbook/configuration/using_parameters_in_dic.rst | 2 +- cookbook/routing/service_container_parameters.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst index 3abe0fbfb5f..7d2c05dabf0 100644 --- a/cookbook/bundles/extension.rst +++ b/cookbook/bundles/extension.rst @@ -91,7 +91,7 @@ The second method has several specific advantages: .. seealso:: - For other usages of the parameter ``%`` syntax see + For parameter handling within a Dependency Injection class see :doc:``. .. index:: diff --git a/cookbook/configuration/using_parameters_in_dic.rst b/cookbook/configuration/using_parameters_in_dic.rst index 72ff3be36e9..c2d869cfa7a 100644 --- a/cookbook/configuration/using_parameters_in_dic.rst +++ b/cookbook/configuration/using_parameters_in_dic.rst @@ -51,7 +51,7 @@ Now, examine the results to see this closely: + xmlns:my-bundle="http://example.org/schema/dic/my_bundle"> diff --git a/cookbook/routing/service_container_parameters.rst b/cookbook/routing/service_container_parameters.rst index b17a03df5b7..de88cee0256 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/cookbook/routing/service_container_parameters.rst @@ -123,5 +123,5 @@ path): .. seealso:: - For other usages of the parameter ``%`` syntax see + For parameter handling within a Dependency Injection class see :doc:``. \ No newline at end of file