Skip to content

Commit 898eac7

Browse files
weaverryanweaverryan
committed
Merge pull request #2322 from richardmiller/adding_parameters_page
Creating parameters page in DI component
2 parents d84746f + 748ec0a commit 898eac7

File tree

5 files changed

+267
-127
lines changed

5 files changed

+267
-127
lines changed

‎book/service_container.rst

Lines changed: 1 addition & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -222,15 +222,6 @@ The end result is exactly the same as before - the difference is only in
222222
to look for parameters with those names. When the container is built, it
223223
looks up the value of each parameter and uses it in the service definition.
224224

225-
.. note::
226-
227-
The percent sign inside a parameter or argument, as part of the string, must
228-
be escaped with another percent sign:
229-
230-
.. code-block:: xml
231-
232-
<argument type="string">http://symfony.com/?foo=%%s&bar=%%d</argument>
233-
234225
The purpose of parameters is to feed information into services. Of course
235226
there was nothing wrong with defining the service without using any parameters.
236227
Parameters, however, have several advantages:
@@ -248,64 +239,6 @@ third-party bundles will *always* use parameters as they make the service
248239
stored in the container more configurable. For the services in your application,
249240
however, you may not need the flexibility of parameters.
250241

251-
Array Parameters
252-
~~~~~~~~~~~~~~~~
253-
254-
Parameters do not need to be flat strings, they can also be arrays. For the XML
255-
format, you need to use the type="collection" attribute for all parameters that are
256-
arrays.
257-
258-
.. configuration-block::
259-
260-
.. code-block:: yaml
261-
262-
# app/config/config.yml
263-
parameters:
264-
my_mailer.gateways:
265-
- mail1
266-
- mail2
267-
- mail3
268-
my_multilang.language_fallback:
269-
en:
270-
- en
271-
- fr
272-
fr:
273-
- fr
274-
- en
275-
276-
.. code-block:: xml
277-
278-
<!-- app/config/config.xml -->
279-
<parameters>
280-
<parameter key="my_mailer.gateways" type="collection">
281-
<parameter>mail1</parameter>
282-
<parameter>mail2</parameter>
283-
<parameter>mail3</parameter>
284-
</parameter>
285-
<parameter key="my_multilang.language_fallback" type="collection">
286-
<parameter key="en" type="collection">
287-
<parameter>en</parameter>
288-
<parameter>fr</parameter>
289-
</parameter>
290-
<parameter key="fr" type="collection">
291-
<parameter>fr</parameter>
292-
<parameter>en</parameter>
293-
</parameter>
294-
</parameter>
295-
</parameters>
296-
297-
.. code-block:: php
298-
299-
// app/config/config.php
300-
use Symfony\Component\DependencyInjection\Definition;
301-
302-
$container->setParameter('my_mailer.gateways', array('mail1', 'mail2', 'mail3'));
303-
$container->setParameter('my_multilang.language_fallback', array(
304-
'en' => array('en', 'fr'),
305-
'fr' => array('fr', 'en'),
306-
));
307-
308-
309242
Importing other Container Configuration Resources
310243
-------------------------------------------------
311244

@@ -967,6 +900,7 @@ its id:
967900
Learn more
968901
----------
969902

903+
* :doc:`/components/dependency_injection/parameters`
970904
* :doc:`/components/dependency_injection/compilation`
971905
* :doc:`/components/dependency_injection/definitions`
972906
* :doc:`/components/dependency_injection/factories`

‎components/dependency_injection/definitions.rst

Lines changed: 3 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,13 @@
22
single: Dependency Injection; Service definitions
33

44

5-
Working with Container Parameters and Definitions
6-
=================================================
7-
8-
Getting and Setting Container Parameters
9-
----------------------------------------
10-
11-
Working with container parameters is straight forward using the container's
12-
accessor methods for parameters. You can check if a parameter has been defined
13-
in the container with::
14-
15-
$container->hasParameter($name);
16-
17-
You can retrieve parameters set in the container with::
18-
19-
$container->getParameter($name);
20-
21-
and set a parameter in the container with::
22-
23-
$container->setParameter($name, $value);
5+
Working with Container Service Definitions
6+
==========================================
247

258
Getting and Setting Service Definitions
269
---------------------------------------
2710

28-
There are also some helpful methods for
29-
working with the service definitions.
11+
There are some helpful methods for working with the service definitions.
3012

3113
To find out if there is a definition for a service id::
3214

‎components/dependency_injection/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
introduction
88
types
9+
parameters
910
definitions
1011
compilation
1112
tags

‎components/dependency_injection/parameters.rst

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
.. index::
2+
single: Dependency Injection; Parameters
3+
4+
Introduction to Parameters
5+
=================================
6+
7+
You can define parameters in the service container which can then be used
8+
directly or as part of service definitions. This can help to separate out
9+
values that you will want to change more regularly.
10+
11+
Getting and Setting Container Parameters
12+
----------------------------------------
13+
14+
Working with container parameters is straight forward using the container's
15+
accessor methods for parameters. You can check if a parameter has been defined
16+
in the container with::
17+
18+
$container->hasParameter('mailer.transport');
19+
20+
You can retrieve parameters set in the container with::
21+
22+
$container->getParameter('mailer.transport');
23+
24+
and set a parameter in the container with::
25+
26+
$container->setParameter('mailer.transport', 'sendmail');
27+
28+
.. note::
29+
30+
You can only set a parameter before the container is compiled. To learn
31+
more about compiling the container see
32+
:doc:`/components/dependency_injection/compilation`
33+
34+
Parameters in Configuration Files
35+
---------------------------------
36+
37+
You can also use the ``parameters`` section of a config file to set parameters:
38+
39+
.. configuration-block::
40+
41+
.. code-block:: yaml
42+
43+
parameters:
44+
mailer.transport: sendmail
45+
46+
.. code-block:: xml
47+
48+
<parameters>
49+
<parameter key="mailer.transport">sendmail</parameter>
50+
</parameters>
51+
52+
.. code-block:: php
53+
54+
$container->setParameter('mailer.transport', 'sendmail');
55+
56+
As well as retrieving the parameter values directly from the container you
57+
can use them in the config files. You can refer to parameters elsewhere in
58+
the config files by surrounding them with percent (``%``) signs, e.g.
59+
``%mailer.transport%``. One use is for this is to inject the values into your
60+
services. This allows you to configure different versions of services between
61+
applications or multiple services based on the same class but configured
62+
differently within a single application. You could inject the choice of mail
63+
transport into the ``Mailer`` class directly but by making it a parameter it
64+
makes it easier to change rather than being tied up with the service definition:
65+
66+
.. configuration-block::
67+
68+
.. code-block:: yaml
69+
70+
parameters:
71+
mailer.transport: sendmail
72+
73+
services:
74+
mailer:
75+
class: Mailer
76+
arguments: ['%mailer.transport%']
77+
78+
.. code-block:: xml
79+
80+
<parameters>
81+
<parameter key="mailer.transport">sendmail</parameter>
82+
</parameters>
83+
84+
<services>
85+
<service id="mailer" class="Mailer">
86+
<argument>%mailer.transport%</argument>
87+
</service>
88+
</services>
89+
90+
.. code-block:: php
91+
92+
use Symfony\Component\DependencyInjection\Reference;
93+
94+
// ...
95+
$container->setParameter('mailer.transport', 'sendmail');
96+
$container
97+
->register('mailer', 'Mailer')
98+
->addArgument('%mailer.transport%');
99+
100+
If we were using this elsewhere as well, then it would only need changing
101+
in one place if a different transport was required.
102+
103+
You can also use the parameters in the service definition, for example,
104+
making the class of a service a parameter:
105+
106+
.. configuration-block::
107+
108+
.. code-block:: yaml
109+
110+
parameters:
111+
mailer.transport: sendmail
112+
mailer.class: Mailer
113+
114+
services:
115+
mailer:
116+
class: '%mailer.class%'
117+
arguments: ['%mailer.transport%']
118+
119+
.. code-block:: xml
120+
121+
<parameters>
122+
<parameter key="mailer.transport">sendmail</parameter>
123+
<parameter key="mailer.class">Mailer</parameter>
124+
</parameters>
125+
126+
<services>
127+
<service id="mailer" class="%mailer.class%">
128+
<argument>%mailer.transport%</argument>
129+
</service>
130+
131+
</services>
132+
133+
.. code-block:: php
134+
135+
use Symfony\Component\DependencyInjection\Reference;
136+
137+
// ...
138+
$container->setParameter('mailer.transport', 'sendmail');
139+
$container->setParameter('mailer.class', 'Mailer');
140+
$container
141+
->register('mailer', '%mailer.class%')
142+
->addArgument('%mailer.transport%');
143+
144+
$container
145+
->register('newsletter_manager', 'NewsletterManager')
146+
->addMethodCall('setMailer', array(new Reference('mailer')));
147+
148+
.. note::
149+
150+
The percent sign inside a parameter or argument, as part of the string, must
151+
be escaped with another percent sign:
152+
153+
.. configuration-block::
154+
155+
.. code-block:: yaml
156+
157+
arguments: ['http://symfony.com/?foo=%%s&bar=%%d']
158+
159+
.. code-block:: xml
160+
161+
<argument type="string">http://symfony.com/?foo=%%s&bar=%%d</argument>
162+
163+
.. code-block:: php
164+
165+
->addArgument('http://symfony.com/?foo=%%s&bar=%%d');
166+
167+
Array Parameters
168+
----------------
169+
170+
Parameters do not need to be flat strings, they can also be arrays. For the XML
171+
format, you need to use the ``type="collection"`` attribute for all parameters that are
172+
arrays.
173+
174+
.. configuration-block::
175+
176+
.. code-block:: yaml
177+
178+
# app/config/config.yml
179+
parameters:
180+
my_mailer.gateways:
181+
- mail1
182+
- mail2
183+
- mail3
184+
my_multilang.language_fallback:
185+
en:
186+
- en
187+
- fr
188+
fr:
189+
- fr
190+
- en
191+
192+
.. code-block:: xml
193+
194+
<!-- app/config/config.xml -->
195+
<parameters>
196+
<parameter key="my_mailer.gateways" type="collection">
197+
<parameter>mail1</parameter>
198+
<parameter>mail2</parameter>
199+
<parameter>mail3</parameter>
200+
</parameter>
201+
<parameter key="my_multilang.language_fallback" type="collection">
202+
<parameter key="en" type="collection">
203+
<parameter>en</parameter>
204+
<parameter>fr</parameter>
205+
</parameter>
206+
<parameter key="fr" type="collection">
207+
<parameter>fr</parameter>
208+
<parameter>en</parameter>
209+
</parameter>
210+
</parameter>
211+
</parameters>
212+
213+
.. code-block:: php
214+
215+
// app/config/config.php
216+
use Symfony\Component\DependencyInjection\Definition;
217+
218+
$container->setParameter('my_mailer.gateways', array('mail1', 'mail2', 'mail3'));
219+
$container->setParameter('my_multilang.language_fallback', array(
220+
'en' => array('en', 'fr'),
221+
'fr' => array('fr', 'en'),
222+
));
223+
224+
Constants as Parameters
225+
-----------------------
226+
227+
The container also has support for setting PHP constants as parameters. To
228+
take advantage of this feature, map the name of your constant to a parameter
229+
key, and define the type as ``constant``.
230+
231+
.. configuration-block::
232+
233+
.. code-block:: xml
234+
235+
<?xml version="1.0" encoding="UTF-8"?>
236+
237+
<container xmlns="http://symfony.com/schema/dic/services"
238+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
239+
240+
<parameters>
241+
<parameter key="global.constant.value" type="constant">GLOBAL_CONSTANT</parameter>
242+
<parameter key="my_class.constant.value" type="constant">My_Class::CONSTANT_NAME</parameter>
243+
</parameters>
244+
</container>
245+
246+
.. code-block:: php
247+
248+
$container->setParameter('global.constant.value', GLOBAL_CONSTANT);
249+
$container->setParameter('my_class.constant.value', My_Class::CONSTANT_NAME);
250+
251+
.. note::
252+
253+
This does not works for Yaml configuration. If you're using Yaml, you can
254+
import an XML file to take advantage of this functionality:
255+
256+
.. configuration-block::
257+
258+
.. code-block:: yaml
259+
260+
# app/config/config.yml
261+
imports:
262+
- { resource: parameters.xml }

0 commit comments

Comments
 (0)