8000 Merge branch '4.0' into 4.1 · Nek-/symfony-docs@71ab3b0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 71ab3b0

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.0' into 4.1
* 4.0: minor symfony#9507 Document the built in env var processors (mcfedr, javiereguiluz)
2 parents a0c278a + 8916422 commit 71ab3b0

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎configuration/external_parameters.rst

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,184 @@ the following:
134134
:doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
135135
problem because the web profiler must **never** be enabled in production.
136136

137+
Environment Variable Processors
138+
-------------------------------
139+
140+
.. versionadded:: 3.4
141+
Environment variable processors were introduced in Symfony 3.4.
142+
143+
The values of the environment variables are considered strings by default.
144+
However, your code may expect other data types, like integers or booleans.
145+
Symfony solves this problem with *processors*, which modify the contents of the
146+
given environment variables. The following example uses the integer processor to
147+
turn the value of the ``HTTP_PORT`` env var into an integer:
148+
149+
.. configuration-block::
150+
151+
.. code-block:: yaml
152+
153+
# config/packages/framework.yaml
154+
framework:
155+
router:
156+
http_port: env(int:HTTP_PORT)
157+
158+
.. code-block:: xml
159+
160+
<!-- config/packages/framework.xml -->
161+
<?xml version="1.0" encoding="UTF-8" ?>
162+
163+
<container xmlns="http://symfony.com/schema/dic/services"
164+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
165+
xmlns:framework="http://symfony.com/schema/dic/symfony"
166+
xsi:schemaLocation="http://symfony.com/schema/dic/services
167+
http://symfony.com/schema/dic/services/services-1.0.xsd
168+
http://symfony.com/schema/dic/symfony
169+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
170+
171+
<framework:config>
172+
<framework:router http_port="%env(int:HTTP_PORT)%" />
173+
</framework:config>
174+
</container>
175+
176+
.. code-block:: php
177+
178+
// config/packages/doctrine.php
179+
$container->loadFromExtension('framework', array(
180+
'router' => array(
181+
'http_port' => '%env(int:HTTP_PORT)%',
182+
)
183+
));
184+
185+
Symfony provides the following env var processors:
186+
187+
``env(string:FOO)``
188+
Casts ``FOO`` to a string:
189+
190+
.. code-block:: yaml
191+
192+
parameters:
193+
env(SECRET): "some_secret"
194+
framework:
195+
secret: '%env(string:SECRET)%'
196+
197+
``env(bool:FOO)``
198+
Casts ``FOO`` to a bool:
199+
200+
.. code-block:: yaml
201+
202+
parameters:
203+
env(HTTP_METHOD_OVERRIDE): "true"
204+
framework:
205+
http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'
206+
207+
``env(int:FOO)``
208+
Casts ``FOO`` to an int.
209+
210+
``env(float:FOO)``
211+
Casts ``FOO`` to an float.
212+
213+
``env(const:FOO)``
214+
Finds the const value named in ``FOO``:
215+
216+
.. code-block:: yaml
217+
218+
parameters:
219+
env(HEALTH_CHECK_METHOD): "Symfony\Component\HttpFoundation\Request:METHOD_HEAD"
220+
security:
221+
access_control:
222+
- { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' }
223+
224+
``env(base64:FOO)``
225+
Decodes the content of ``FOO``, which is a base64 encoded string.
226+
227+
``env(json:FOO)``
228+
Decodes the content of ``FOO``, which is a JSON encoded string. It returns
229+
either an array or ``null``:
230+
231+
.. code-block:: yaml
232+
233+
parameters:
234+
env(TRUSTED_HOSTS): "['10.0.0.1', '10.0.0.2']"
235+
framework:
236+
trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
237+
238+
``env(resolve:FOO)``
239+
Replaces the string ``FOO`` by the value of a config parameter with the
240+
same name:
241+
242+
.. code-block:: yaml
243+
244+
parameters:
245+
env(HOST): '10.0.0.1'
246+
env(SENTRY_DSN): "http://%env(HOST)%/project"
247+
sentry:
248+
dsn: '%env(resolve:SENTRY_DSN)%'
249+
250+
``env(csv:FOO)``
251+
Decodes the content of ``FOO``, which is a CSV-encoded string:
252+
253+
.. code-block:: yaml
254+
255+
parameters:
256+
env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2"
257+
framework:
258+
trusted_hosts: '%env(csv:TRUSTED_HOSTS)%'
259+
260+
``env(file:FOO)``
261+
Returns the contents of a file whose path is the value of the ``FOO`` env var:
262+
263+
.. code-block:: yaml
264+
265+
parameters:
266+
env(AUTH_FILE): "../config/auth.json"
267+
google:
268+
auth: '%env(file:AUTH_FILE)%'
269+
270+
It is also possible to combine any number of processors:
271+
272+
.. code-block:: yaml
273+
274+
parameters:
275+
env(AUTH_FILE): "%kernel.project_dir%/config/auth.json"
276+
google:
277+
# 1. gets the value of the AUTH_FILE env var
278+
# 2. replaces the values of any config param to get the config path
279+
# 3. gets the content of the file stored in that path
280+
# 4. JSON-decodes the content of the file and returns it
281+
auth: '%env(json:file:resolve:AUTH_FILE)%'
282+
283+
Custom Environment Variable Processors
284+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285+
286+
It's also possible to add your own processors for environment variables. First,
287+
create a class that implements
288+
:class:`Symfony\\Component\\DependencyInjection\\EnvVarProcessorInterface` and
289+
then, define a service for that class::
290+
291+
class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
292+
{
293+
private $container;
294+
295+
public function __construct(ContainerInterface $container)
296+
{
297+
$this->container = $container;
298+
}
299+
300+
public function getEnv($prefix, $name, \Closure $getEnv)
301+
{
302+
$env = $getEnv($name);
303+
304+
return strtolower($env);
305+
}
306+
307+
public static function getProvidedTypes()
308+
{
309+
return [
310+
'lowercase' => 'string',
311+
];
312+
}
313+
}
314+
137315
Constants
138316
---------
139317

0 commit comments

Comments
 (0)
0