[DependencyInjection] Document %env(...)% dynamic parameters #6918

nicolas-grekas · 2016-08-25T12:25:45Z

Ref. symfony/symfony#19681

tgalopin · 2016-08-25T12:37:59Z

configuration/external_parameters.rst

+        $container->setParameter('env(DATABASE_HOST)', 'localhost');
+
+Unlike ``SYMFONY__`` prefixed environment variables, ``%env(...)%`` parameters are
+truned into run-time environment variable reads, so that dumped containers can


wouterj · 2016-08-25T15:12:36Z

configuration/external_parameters.rst

+be reconfigured dynamically even after being compiled.
+
+.. versionadded:: 3.2
+    ``env(...)`` parameters were introduced in Symfony 3.2.


please put the versionadded directive after the section header, instead of at the end

wouterj · 2016-08-28T16:07:16Z

status: needs work

@magnusnordlander

…env(MY_ENV_VAR)% (nicolas-grekas) This PR was merged into the 3.2-dev branch. Discussion ---------- [DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% | Q | A | ------------- | --- | Branch? | master | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #10138, #7555, #16403, #18155 | License | MIT | Doc PR | symfony/symfony-docs#6918 This is an alternative approach to #18155 for injecting env vars into container configurations. With this PR, anywhere parameters are allowed, one can use `%env(ENV_VAR)%` to inject a dynamic env var. Additionally, if one sets a value to such parameters in e.g. the `parameter.yml` file (`env(ENV_VAR): foo`), this value will be used as a default value when the env var is not defined. If no default value is specified, an `EnvVarNotFoundException` will be thrown at runtime. Unlike previous attempts that also used parameters (#16403), the implementation is compatible with DI extensions: before being dumped, env vars are resolved to uniquely identifiable string placeholders that can get through DI extensions manipulations. When dumped, these unique placeholders are replaced by dynamic calls to a getEnv method.. ping @magnusnordlander @dzuelke @fabpot Commits ------- bac2132 [DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% syntax

@magnusnordlander

…env(MY_ENV_VAR)% (nicolas-grekas) This PR was merged into the 3.2-dev branch. Discussion ---------- [DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% | Q | A | ------------- | --- | Branch? | master | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #10138, #7555, #16403, #18155 | License | MIT | Doc PR | symfony/symfony-docs#6918 This is an alternative approach to #18155 for injecting env vars into container configurations. With this PR, anywhere parameters are allowed, one can use `%env(ENV_VAR)%` to inject a dynamic env var. Additionally, if one sets a value to such parameters in e.g. the `parameter.yml` file (`env(ENV_VAR): foo`), this value will be used as a default value when the env var is not defined. If no default value is specified, an `EnvVarNotFoundException` will be thrown at runtime. Unlike previous attempts that also used parameters (#16403), the implementation is compatible with DI extensions: before being dumped, env vars are resolved to uniquely identifiable string placeholders that can get through DI extensions manipulations. When dumped, these unique placeholders are replaced by dynamic calls to a getEnv method.. ping @magnusnordlander @dzuelke @fabpot Commits ------- bac2132 [DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% syntax

@magnusnordlander

…env(MY_ENV_VAR)% (nicolas-grekas) This PR was merged into the 3.2-dev branch. Discussion ---------- [DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% | Q | A | ------------- | --- | Branch? | master | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #10138, #7555, #16403, #18155 | License | MIT | Doc PR | symfony/symfony-docs#6918 This is an alternative approach to #18155 for injecting env vars into container configurations. With this PR, anywhere parameters are allowed, one can use `%env(ENV_VAR)%` to inject a dynamic env var. Additionally, if one sets a value to such parameters in e.g. the `parameter.yml` file (`env(ENV_VAR): foo`), this value will be used as a default value when the env var is not defined. If no default value is specified, an `EnvVarNotFoundException` will be thrown at runtime. Unlike previous attempts that also used parameters (#16403), the implementation is compatible with DI extensions: before being dumped, env vars are resolved to uniquely identifiable string placeholders that can get through DI extensions manipulations. When dumped, these unique placeholders are replaced by dynamic calls to a getEnv method.. ping @magnusnordlander @dzuelke @fabpot Commits ------- bac2132 [DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% syntax

weaverryan

Status: Reviewed

Setting this as reviewed because all of my comments are very minor!

weaverryan · 2016-09-18T20:46:00Z

configuration/external_parameters.rst

+
+    .. code-block:: yaml
+
+        parameters:


Add #app/config/parameters.yml above this - it's probably the file where they will define the default value

weaverryan · 2016-09-18T20:47:12Z

configuration/external_parameters.rst

            )
        ));

+``env(...)`` parameters can have default values be set and used whenever their
+corresponding environment variables are not found:


You can also give the ``env(...)`` parameters a default value: the default value will be used whenever the corresponding environment variable is *not* found:

weaverryan · 2016-09-18T20:51:47Z

configuration/external_parameters.rst

+.. note::
+
+    All popular web servers support setting environment variables. Read their
+    documentation to know how.


... to find out how.

weaverryan · 2016-09-18T20:51:58Z

configuration/external_parameters.rst

+.. note::
+
+    You can also define the default value of any existing parameters using
+    special environement variables named after their corresponding parameter


environment

weaverryan · 2016-09-18T20:54:54Z

Status: Reviewed

Just needs a few minor changes.

wouterj · 2016-09-18T21:02:27Z

configuration/external_parameters.rst

+    You can also define the default value of any existing parameters using
+    special environement variables named after their corresponding parameter
+    prefixed with ``SYMFONY__`` after replacing dots by double underscores
+    (e.g. ``SYMFONY__FOO__BAR`` to set the default value of the ``foo.bar``


let's keep using a real example here: (e.g.SYMFONY__DATABASE__USERto set the default value of thedatabase.user` parameter).

nicolas-grekas · 2016-09-19T18:57:39Z

Comments addressed, thanks for the review.

wouterj · 2016-10-01T11:51:56Z

👍

mickadoo · 2016-10-11T22:42:34Z

configuration/external_parameters.rst

+        #app/config/parameters.yml
+
+        parameters:
+            env(DATABASE_HOST): localhost


Is this functionality part of the symfony/symfony#19681 PR? I've tried something similar with:

database_driver: 'env(DATABASE_DRIVER): pdo_mysql'

but it doesn't use the default and just complains that:

"The given 'driver' env(DATABASE_DRIVER): pdo_mysql is unknown"

@mickadoo your code is not what is documented here

@stof I just thought I'd try it out, didn't work though

What's documented here is:

parameters: database_driver: '%env(DATABASE_DRIVER)%' env(DATABASE_DRIVER): pdo_mysql

Which, as you can see, is quite different from the format you tested. If there is something we can do to improve the description of the feature, please tell us!

@wouterj Ah, I get it now. Sorry about that!

No problem @mickadoo thanks for test-casing this documentation proposal.

I think we should include the database_driver: '%env(DATABASE_DRIVER)%' line in this example to avoid confusing for other readers.

xabbuh · 2016-10-13T20:08:42Z

configuration/external_parameters.rst

-
-You can now reference these parameters wherever you need them.
+For example, if you want to use the value of the ``DATABASE_HOST`` environment
+variable into you service container configuration, you can reference it using


[...] variable in your service container configuration [...]

xabbuh · 2016-10-13T20:09:33Z

configuration/external_parameters.rst

+
+    .. code-block:: yaml
+
+        #app/config/parameters.yml


missing space between comment and "app"

xabbuh · 2016-10-13T20:09:45Z

configuration/external_parameters.rst

+    .. code-block:: yaml
+
+        #app/config/parameters.yml
+


blank line should be removed

xabbuh · 2016-10-13T20:10:00Z

configuration/external_parameters.rst

+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>


missing filename comment

same for the PHP config example

Do you have an example of such filenames for xml & php?

We usually simply replace the file extension. So here we would have app/config/parameters.yml, app/config/parameters.xml, and app/config/parameters.php. By the way, can you also add similar comments in the example above to, but using config.yml, config.xml, and config.php there?

Ah well, the previous example is not new. We should add the comments there in older branches too and can probably better do that in a separate PR.

got it, fixed

xabbuh · 2016-10-13T20:11:32Z

configuration/external_parameters.rst

+
+        $container->setParameter('env(DATABASE_HOST)', 'localhost');
+
+If you're using Apache, environment variables can be set e.g. using the following


Everywhere else we give examples for Nginx too IIRC. I think we should do the same here.

xabbuh · 2016-10-13T20:12:26Z

configuration/external_parameters.rst

+        <Directory "/path/to/symfony_2_app/web">
+            AllowOverride All
+            Allow from All
+        </Directory>


We should also add a placeholder comment to indicate that this config is not a complete working examples, but only shows how to configure environment variables for a virtual host.

wouterj · 2016-10-16T16:02:40Z

status: needs work

ping @nicolas-grekas

nicolas-grekas · 2016-10-21T07:15:53Z

comments addressed
Status: needs review

javiereguiluz · 2016-10-21T07:31:32Z

configuration/external_parameters.rst

-    .. code-block:: terminal
+You can reference environment variables by using special parameters named after
+the variables you want to use enclosed between ``env()``. Their actual values
+will be resolved at runtime, so that dumped containers can be reconfigured


A quick question about this:

Their actual values will be resolved at runtime [...]

Are they resolved at runtime every time they are used ... or are they resolved just the first time they are used and then Symfony reuses the cached value? I say this because of the code of the getEnv() method.

Per request they are resolved once. But if you change the value, during the next request you will see the new value (again resolved only once during this request). Should we make that more clear somehow?

Thanks @xabbuh. I wouldn't add any notice about this because that behavior is exactly what we should expect.

I added (once per request), good enough?

nicolas-grekas · 2016-10-23T16:20:12Z

configuration/external_parameters.rst

+
+.. configuration-block::
+
+    .. code-block:: apache


looking at the tests, apache here makes sphinx fail, any clue why?

Apache has no label configured. Please edit the _build/conf.py file and add: 'apache': 'Apache' (same for the other formats in this block). (and also ping javier that the symfony.com config has to be updated)

@wouterj thanks for the heads up. It will be merged in symfony.com soon:

@javiereguiluz please note that you also have to add 'nginx': 'NGINX'

@wouterj thanks! It's fixed now. I opted for Nginx as the human-readable name instead of NGINX. The official website mixes nginx, Nginx and NGINX ... but the Wikipedia always uses Nginx.

wouterj · 2016-11-09T12:26:35Z

👍
status: reviewed

Note to merger: Please fix the conf.py configuration to suppor the new configuration block formats.

wouterj · 2016-11-19T16:38:26Z

ping @javiereguiluz @weaverryan @xabbuh please review & vote

javiereguiluz · 2016-11-19T17:45:14Z

configuration/external_parameters.rst

            )
        ));

+You can also give the ``env()`` parameters a default value: the default value


... a default value: the default value will be used whenever ...

-->

... a default value used whenever ...

javiereguiluz

👍

xabbuh · 2016-12-08T20:27:32Z

👍

xabbuh · 2016-12-14T18:43:39Z

Thank you Nicolas.

…eters (nicolas-grekas) This PR was merged into the 3.2 branch. Discussion ---------- [DependencyInjection] Document %env(...)% dynamic parameters Ref. symfony/symfony#19681 Commits ------- 083da46 [DI] Document %env()% dynamic parameters

carsonbot added the Status: Needs Review label Aug 25, 2016

nicolas-grekas force-pushed the env-params branch from 8f1d491 to 0eae3eb Compare August 25, 2016 12:30

nicolas-grekas mentioned this pull request Aug 25, 2016

[DI] Allow injecting ENV parameters at runtime using %env(MY_ENV_VAR)% symfony/symfony#19681

Merged

tgalopin reviewed Aug 25, 2016
View reviewed changes

nicolas-grekas force-pushed the env-params branch 2 times, most recently from d816802 to 9f7017e Compare August 25, 2016 12:39

wouterj reviewed Aug 25, 2016
View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels Aug 28, 2016

javiereguiluz changed the title ~~[DI] Document %env(...)% dynamic parameters~~ [WCM][DependencyInjection] Document %env(...)% dynamic parameters Aug 29, 2016

nicolas-grekas force-pushed the env-params branch from 9f7017e to 3021c4f Compare September 2, 2016 09:21

carsonbot added Status: Needs Review and removed Status: Needs Work labels Sep 2, 2016

weaverryan changed the title ~~[WCM][DependencyInjection] Document %env(...)% dynamic parameters~~ [DependencyInjection] Document %env(...)% dynamic parameters Sep 18, 2016

weaverryan requested changes Sep 18, 2016

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Sep 18, 2016

wouterj reviewed Sep 18, 2016

View reviewed changes

nicolas-grekas force-pushed the env-params branch from 3021c4f to 68e9b49 Compare September 19, 2016 18:57

wouterj approved these changes Oct 1, 2016

View reviewed changes

mickadoo reviewed Oct 11, 2016

View reviewed changes

nicolas-grekas force-pushed the env-params branch from 68e9b49 to 27399c0 Compare October 12, 2016 14:28

xabbuh reviewed Oct 13, 2016

View reviewed changes

configuration/external_parameters.rst

.. code-block:: yaml

#app/config/parameters.yml

Copy link

Member

xabbuh Oct 13, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing space between comment and "app"

xabbuh reviewed Oct 13, 2016

View reviewed changes

configuration/external_parameters.rst

.. code-block:: yaml

#app/config/parameters.yml

Copy link

Member

xabbuh Oct 13, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blank line should be removed

xabbuh reviewed Oct 13, 2016

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Reviewed labels Oct 16, 2016

nicolas-grekas force-pushed the env-params branch from 27399c0 to 21d6a75 Compare October 21, 2016 07:15

carsonbot added Status: Needs Review and removed Status: Needs Work labels Oct 21, 2016

javiereguiluz reviewed Oct 21, 2016

View reviewed changes

[DI] Document %env()% dynamic parameters

083da46

nicolas-grekas force-pushed the env-params branch from 21d6a75 to 083da46 Compare October 21, 2016 08:05

nicolas-grekas commented Oct 23, 2016

View reviewed changes

wouterj added this to the 3.2 milestone Nov 9, 2016

carsonbot added Status: Reviewed and removed Status: Needs Review labels Nov 9, 2016

javiereguiluz reviewed Nov 19, 2016

View reviewed changes

javiereguiluz approved these changes Nov 19, 2016

View reviewed changes

xabbuh changed the base branch from master to 3.2 December 8, 2016 20:26

xabbuh merged commit 083da46 into symfony:3.2 Dec 14, 2016

nicolas-grekas deleted the env-params branch July 1, 2018 20:44


		$container->setParameter('env(DATABASE_HOST)', 'localhost');

		If you're using Apache, environment variables can be set e.g. using the following

Uh oh!

[DependencyInjection] Document %env(...)% dynamic parameters #6918

[DependencyInjection] Document %env(...)% dynamic parameters #6918

Uh oh!

Conversation

nicolas-grekas commented Aug 25, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterj commented Aug 28, 2016

Uh oh!

weaverryan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weaverryan commented Sep 18, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicolas-grekas commented Sep 19, 2016

Uh oh!

wouterj commented Oct 1, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mickadoo Oct 13, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterj commented Oct 16, 2016

Uh oh!

nicolas-grekas commented Oct 21, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

nicolas-grekas commented Aug 25, 2016 •

edited

Loading

mickadoo Oct 13, 2016 •

edited

Loading