diff --git a/book/service_container.rst b/book/service_container.rst
index 917eb0264e0..2ac44598a11 100644
--- a/book/service_container.rst
+++ b/book/service_container.rst
@@ -222,15 +222,6 @@ The end result is exactly the same as before - the difference is only in
to look for parameters with those names. When the container is built, it
looks up the value of each parameter and uses it in the service definition.
-.. note::
-
- The percent sign inside a parameter or argument, as part of the string, must
- be escaped with another percent sign:
-
- .. code-block:: xml
-
- http://symfony.com/?foo=%%s&bar=%%d
-
The purpose of parameters is to feed information into services. Of course
there was nothing wrong with defining the service without using any parameters.
Parameters, however, have several advantages:
@@ -248,64 +239,6 @@ third-party bundles will *always* use parameters as they make the service
stored in the container more configurable. For the services in your application,
however, you may not need the flexibility of parameters.
-Array Parameters
-~~~~~~~~~~~~~~~~
-
-Parameters do not need to be flat strings, they can also be arrays. For the XML
-format, you need to use the type="collection" attribute for all parameters that are
-arrays.
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/config.yml
- parameters:
- my_mailer.gateways:
- - mail1
- - mail2
- - mail3
- my_multilang.language_fallback:
- en:
- - en
- - fr
- fr:
- - fr
- - en
-
- .. code-block:: xml
-
-
-
-
- mail1
- mail2
- mail3
-
-
-
- en
- fr
-
-
- fr
- en
-
-
-
-
- .. code-block:: php
-
- // app/config/config.php
- use Symfony\Component\DependencyInjection\Definition;
-
- $container->setParameter('my_mailer.gateways', array('mail1', 'mail2', 'mail3'));
- $container->setParameter('my_multilang.language_fallback', array(
- 'en' => array('en', 'fr'),
- 'fr' => array('fr', 'en'),
- ));
-
-
Importing other Container Configuration Resources
-------------------------------------------------
@@ -967,6 +900,7 @@ its id:
Learn more
----------
+* :doc:`/components/dependency_injection/parameters`
* :doc:`/components/dependency_injection/compilation`
* :doc:`/components/dependency_injection/definitions`
* :doc:`/components/dependency_injection/factories`
diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst
index d8acaac9002..2f6ae3e7a9a 100644
--- a/components/dependency_injection/definitions.rst
+++ b/components/dependency_injection/definitions.rst
@@ -2,31 +2,13 @@
single: Dependency Injection; Service definitions
-Working with Container Parameters and Definitions
-=================================================
-
-Getting and Setting Container Parameters
-----------------------------------------
-
-Working with container parameters is straight forward using the container's
-accessor methods for parameters. You can check if a parameter has been defined
-in the container with::
-
- $container->hasParameter($name);
-
-You can retrieve parameters set in the container with::
-
- $container->getParameter($name);
-
-and set a parameter in the container with::
-
- $container->setParameter($name, $value);
+Working with Container Service Definitions
+==========================================
Getting and Setting Service Definitions
---------------------------------------
-There are also some helpful methods for
-working with the service definitions.
+There are some helpful methods for working with the service definitions.
To find out if there is a definition for a service id::
diff --git a/components/dependency_injection/index.rst b/components/dependency_injection/index.rst
index 2b60d8576d3..e1d6b0eab8d 100644
--- a/components/dependency_injection/index.rst
+++ b/components/dependency_injection/index.rst
@@ -6,6 +6,7 @@
introduction
types
+ parameters
definitions
compilation
tags
diff --git a/components/dependency_injection/parameters.rst b/components/dependency_injection/parameters.rst
new file mode 100644
index 00000000000..567f4ac5467
--- /dev/null
+++ b/components/dependency_injection/parameters.rst
@@ -0,0 +1,262 @@
+.. index::
+ single: Dependency Injection; Parameters
+
+Introduction to Parameters
+=================================
+
+You can define parameters in the service container which can then be used
+directly or as part of service definitions. This can help to separate out
+values that you will want to change more regularly.
+
+Getting and Setting Container Parameters
+----------------------------------------
+
+Working with container parameters is straight forward using the container's
+accessor methods for parameters. You can check if a parameter has been defined
+in the container with::
+
+ $container->hasParameter('mailer.transport');
+
+You can retrieve parameters set in the container with::
+
+ $container->getParameter('mailer.transport');
+
+and set a parameter in the container with::
+
+ $container->setParameter('mailer.transport', 'sendmail');
+
+.. note::
+
+ You can only set a parameter before the container is compiled. To learn
+ more about compiling the container see
+ :doc:`/components/dependency_injection/compilation`
+
+Parameters in Configuration Files
+---------------------------------
+
+You can also use the ``parameters`` section of a config file to set parameters:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ parameters:
+ mailer.transport: sendmail
+
+ .. code-block:: xml
+
+
+ sendmail
+
+
+ .. code-block:: php
+
+ $container->setParameter('mailer.transport', 'sendmail');
+
+As well as retrieving the parameter values directly from the container you
+can use them in the config files. You can refer to parameters elsewhere in
+the config files by surrounding them with percent (``%``) signs, e.g.
+``%mailer.transport%``. One use is for this is to inject the values into your
+services. This allows you to configure different versions of services between
+applications or multiple services based on the same class but configured
+differently within a single application. You could inject the choice of mail
+transport into the ``Mailer`` class directly but by making it a parameter it
+makes it easier to change rather than being tied up with the service definition:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ parameters:
+ mailer.transport: sendmail
+
+ services:
+ mailer:
+ class: Mailer
+ arguments: ['%mailer.transport%']
+
+ .. code-block:: xml
+
+
+ sendmail
+
+
+
+
+ %mailer.transport%
+
+
+
+ .. code-block:: php
+
+ use Symfony\Component\DependencyInjection\Reference;
+
+ // ...
+ $container->setParameter('mailer.transport', 'sendmail');
+ $container
+ ->register('mailer', 'Mailer')
+ ->addArgument('%mailer.transport%');
+
+If we were using this elsewhere as well, then it would only need changing
+in one place if a different transport was required.
+
+You can also use the parameters in the service definition, for example,
+making the class of a service a parameter:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ parameters:
+ mailer.transport: sendmail
+ mailer.class: Mailer
+
+ services:
+ mailer:
+ class: '%mailer.class%'
+ arguments: ['%mailer.transport%']
+
+ .. code-block:: xml
+
+
+ sendmail
+ Mailer
+
+
+
+
+ %mailer.transport%
+
+
+
+
+ .. code-block:: php
+
+ use Symfony\Component\DependencyInjection\Reference;
+
+ // ...
+ $container->setParameter('mailer.transport', 'sendmail');
+ $container->setParameter('mailer.class', 'Mailer');
+ $container
+ ->register('mailer', '%mailer.class%')
+ ->addArgument('%mailer.transport%');
+
+ $container
+ ->register('newsletter_manager', 'NewsletterManager')
+ ->addMethodCall('setMailer', array(new Reference('mailer')));
+
+.. note::
+
+ The percent sign inside a parameter or argument, as part of the string, must
+ be escaped with another percent sign:
+
+ .. configuration-block::
+
+ .. code-block:: yaml
+
+ arguments: ['http://symfony.com/?foo=%%s&bar=%%d']
+
+ .. code-block:: xml
+
+ http://symfony.com/?foo=%%s&bar=%%d
+
+ .. code-block:: php
+
+ ->addArgument('http://symfony.com/?foo=%%s&bar=%%d');
+
+Array Parameters
+----------------
+
+Parameters do not need to be flat strings, they can also be arrays. For the XML
+format, you need to use the ``type="collection"`` attribute for all parameters that are
+arrays.
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ parameters:
+ my_mailer.gateways:
+ - mail1
+ - mail2
+ - mail3
+ my_multilang.language_fallback:
+ en:
+ - en
+ - fr
+ fr:
+ - fr
+ - en
+
+ .. code-block:: xml
+
+
+
+
+ mail1
+ mail2
+ mail3
+
+
+
+ en
+ fr
+
+
+ fr
+ en
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
+ use Symfony\Component\DependencyInjection\Definition;
+
+ $container->setParameter('my_mailer.gateways', array('mail1', 'mail2', 'mail3'));
+ $container->setParameter('my_multilang.language_fallback', array(
+ 'en' => array('en', 'fr'),
+ 'fr' => array('fr', 'en'),
+ ));
+
+Constants as Parameters
+-----------------------
+
+The container also has support for setting PHP constants as parameters. To
+take advantage of this feature, map the name of your constant to a parameter
+key, and define the type as ``constant``.
+
+.. configuration-block::
+
+ .. code-block:: xml
+
+
+
+
+
+
+ GLOBAL_CONSTANT
+ My_Class::CONSTANT_NAME
+
+
+
+ .. code-block:: php
+
+ $container->setParameter('global.constant.value', GLOBAL_CONSTANT);
+ $container->setParameter('my_class.constant.value', My_Class::CONSTANT_NAME);
+
+.. note::
+
+ This does not works for Yaml configuration. If you're using Yaml, you can
+ import an XML file to take advantage of this functionality:
+
+ .. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ imports:
+ - { resource: parameters.xml }
diff --git a/cookbook/configuration/external_parameters.rst b/cookbook/configuration/external_parameters.rst
index e1df9545d65..dc588dba691 100644
--- a/cookbook/configuration/external_parameters.rst
+++ b/cookbook/configuration/external_parameters.rst
@@ -94,45 +94,6 @@ You can now reference these parameters wherever you need them.
)
));
-Constants
----------
-
-The container also has support for setting PHP constants as parameters. To
-take advantage of this feature, map the name of your constant to a parameter
-key, and define the type as ``constant``.
-
-.. code-block:: xml
-
-
-
-
-
-
- GLOBAL_CONSTANT
- My_Class::CONSTANT_NAME
-
-
-
-.. note::
-
- This only works for XML configuration. If you're *not* using XML, simply
- import an XML file to take advantage of this functionality:
-
- .. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/config.yml
- imports:
- - { resource: parameters.xml }
-
- .. code-block:: php
-
- // app/config/config.php
- $loader->import('parameters.xml');
-
-
Miscellaneous Configuration
---------------------------