Skip to content

Commit ba095e8

Browse files
richardmiller-zzrichardmiller-zz
committed
Creating parameters page in DI component
1 parent 9dfb144 commit ba095e8

File tree

5 files changed

+257
-127
lines changed

5 files changed

+257
-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: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
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+
89+
</services>
90+
91+
.. code-block:: php
92+
93+
use Symfony\Component\DependencyInjection\Reference;
94+
95+
// ...
96+
$container->setParameter('mailer.transport', 'sendmail');
97+
$container
98+
->register('mailer', 'Mailer')
99+
->addArgument('%mailer.transport%');
100+
101+
If we were using this elsewhere as well, then it would only need changing
102+
in one place if a different transport was required.
103+
104+
You can also use the parameters in the service definition, for example,
105+
making the class of a service a parameter:
106+
107+
.. configuration-block::
108+
109+
.. code-block:: yaml
110+
111+
parameters:
112+
mailer.transport: sendmail
113+
mailer.class: Mailer
114+
115+
services:
116+
mailer:
117+
class: %mailer.class%
118+
arguments: [%mailer.transport%]
119+
120+
.. code-block:: xml
121+
122+
<parameters>
123+
<parameter key="mailer.transport">sendmail</parameter>
124+
<parameter key="mailer.class">Mailer</parameter>
125+
</parameters>
126+
127+
<services>
128+
<service id="mailer" class="%mailer.class%">
129+
<argument>%mailer.transport%</argument>
130+
</service>
131+
132+
</services>
133+
134+
.. code-block:: php
135+
136+
use Symfony\Component\DependencyInjection\Reference;
137+
138+
// ...
139+
$container->setParameter('mailer.transport', 'sendmail');
140+
$container->setParameter('mailer.class', 'Mailer');
141+
$container
142+
->register('mailer', '%mailer.class%')
143+
->addArgument('%mailer.transport%');
144+
145+
$container
146+
->register('newsletter_manager', 'NewsletterManager')
147+
->addMethodCall('setMailer', array(new Reference('mailer')));
148+
149+
.. note::
150+
151+
The percent sign inside a parameter or argument, as part of the string, must
152+
be escaped with another percent sign:
153+
154+
.. code-block:: xml
155+
156+
<argument type="string">http://symfony.com/?foo=%%s&bar=%%d</argument>
157+
158+
Array Parameters
159+
----------------
160+
161+
Parameters do not need to be flat strings, they can also be arrays. For the XML
162+
format, you need to use the type="collection" attribute for all parameters that are
163+
arrays.
164+
165+
.. configuration-block::
166+
167+
.. code-block:: yaml
168+
169+
# app/config/config.yml
170+
parameters:
171+
my_mailer.gateways:
172+
- mail1
173+
- mail2
174+
- mail3
175+
my_multilang.language_fallback:
176+
en:
177+
- en
178+
- fr
179+
fr:
180+
- fr
181+
- en
182+
183+
.. code-block:: xml
184+
185+
<!-- app/config/config.xml -->
186+
<parameters>
187+
<parameter key="my_mailer.gateways" type="collection">
188+
<parameter>mail1</parameter>
189+
<parameter>mail2</parameter>
190+
<parameter>mail3</parameter>
191+
</parameter>
192+
<parameter key="my_multilang.language_fallback" type="collection">
193+
<parameter key="en" type="collection">
194+
<parameter>en</parameter>
195+
<parameter>fr</parameter>
196+
</parameter>
197+
<parameter key="fr" type="collection">
198+
<parameter>fr</parameter>
199+
<parameter>en</parameter>
200+
</parameter>
201+
</parameter>
202+
</parameters>
203+
204+
.. code-block:: php
205+
206+
// app/config/config.php
207+
use Symfony\Component\DependencyInjection\Definition;
208+
209+
$container->setParameter('my_mailer.gateways', array('mail1', 'mail2', 'mail3'));
210+
$container->setParameter('my_multilang.language_fallback', array(
211+
'en' => array('en', 'fr'),
212+
'fr' => array('fr', 'en'),
213+
));
214+
215+
Constants as Parameters
216+
-----------------------
217+
218+
The container also has support for setting PHP constants as parameters. To
219+
take advantage of this feature, map the name of your constant to a parameter
220+
key, and define the type as ``constant``.
221+
222+
.. code-block:: xml
223+
224+
<?xml version="1.0" encoding="UTF-8"?>
225+
226+
<container xmlns="http://symfony.com/schema/dic/services"
227+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
228+
229+
<parameters>
230+
<parameter key="global.constant.value" type="constant">GLOBAL_CONSTANT</parameter>
231+
<parameter key="my_class.constant.value" type="constant">My_Class::CONSTANT_NAME</parameter>
232+
</parameters>
233+
</container>
234+
235+
.. note::
236+
237+
This only works for XML configuration. If you're *not* using XML, simply
238+
import an XML file to take advantage of this functionality:
239+
240+
.. configuration-block::
241+
242+
.. code-block:: yaml
243+
244+
# app/config/config.yml
245+
imports:
246+
- { resource: parameters.xml }
247+
248+
.. code-block:: php
249+
250+
// app/config/config.php
251+
$loader->import('parameters.xml');
252+

0 commit comments

Comments
 (0)