From cd353c710eefb86ed328585456f76b353d51543a Mon Sep 17 00:00:00 2001 From: Fred Cox Date: Tue, 27 Mar 2018 23:11:03 +0300 Subject: [PATCH 1/4] Add description of the built in envvar processors --- configuration/external_parameters.rst | 80 +++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst index 375360985d3..582f1e1d1e5 100644 --- a/configuration/external_parameters.rst +++ b/configuration/external_parameters.rst @@ -99,6 +99,86 @@ will be used whenever the corresponding environment variable is *not* found: // config/services.php $container->setParameter('env(DATABASE_HOST)', 'localhost'); +Environment Variable Processors +------------------------------- + +When using environment variables they are always strings by default, but sometimes +you will want to have specific types so that they match the types expected by your code. + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/framework.yaml + framework: + router: + http_port: env(int:HTTP_PORT) + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // config/packages/doctrine.php + $container->loadFromExtension('framework', array( + 'router' => array( + 'http_port' => '%env(int:HTTP_PORT)%', + ) + )); + +A number of different types are supported: + +``env(string):FOO)`` + Casts ``FOO`` to a string + +``env(bool:FOO)`` + Casts ``FOO`` to a bool + +``env(int:FOO)`` + Casts ``FOO`` to an int + +``env(float:FOO)`` + Casts ``FOO`` to an float + +``env(const:FOO)`` + Finds the const value named in ``FOO`` + +``env(base64:FOO)`` + Decodes ``FOO`` that is a base64 encoded string + +``env(json:FOO)`` + Decodes ``FOO`` that is a json encoded string into either an array or ``null`` + +``env(resolve:FOO)`` + Resolves references in the string ``FOO`` to other parameters + +``env(csv:FOO)`` + Decodes ``FOO`` that is a single row of comma seperated values + +``env(file:FOO)`` + Reads the contents of a file named in ``FOO`` + +It is also possible to combine the processors: + +``env(json:file:FOO)`` + Reads the contents of a file named in ``FOO``, and then decode it from json, resulting in an array or ``null`` + + .. _configuration-env-var-in-prod: Configuring Environment Variables in Production From 67227a67c51fca561e53b086310377f1bad0326b Mon Sep 17 00:00:00 2001 From: Fred Cox Date: Thu, 24 May 2018 20:05:54 +0300 Subject: [PATCH 2/4] Add examples for parameter processors --- configuration/external_parameters.rst | 60 ++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst index 582f1e1d1e5..147612d4731 100644 --- a/configuration/external_parameters.rst +++ b/configuration/external_parameters.rst @@ -143,12 +143,26 @@ you will want to have specific types so that they match the types expected by yo A number of different types are supported: -``env(string):FOO)`` +``env(string:FOO)`` Casts ``FOO`` to a string + +.. code-block:: php + + parameters: + env(SECRET): "some_secret" + framework: + secret: '%env(string:SECRET)%' ``env(bool:FOO)`` Casts ``FOO`` to a bool +.. code-block:: php + + parameters: + env(HTTP_METHOD_OVERRIDE): "true" + framework: + http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%' + ``env(int:FOO)`` Casts ``FOO`` to an int @@ -158,26 +172,70 @@ A number of different types are supported: ``env(const:FOO)`` Finds the const value named in ``FOO`` +.. code-block:: php + + parameters: + env(HEALTH_CHECK_METHOD): "Symfony\Component\HttpFoundation\Request:METHOD_HEAD" + security: + access_control: + - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' } + ``env(base64:FOO)`` Decodes ``FOO`` that is a base64 encoded string ``env(json:FOO)`` Decodes ``FOO`` that is a json encoded string into either an array or ``null`` + +.. code-block:: php + + parameters: + env(TRUSTED_HOSTS): "['10.0.0.1', '10.0.0.2']" + framework: + trusted_hosts: '%env(json:TRUSTED_HOSTS)%' ``env(resolve:FOO)`` Resolves references in the string ``FOO`` to other parameters + +.. code-block:: php + + parameters: + env(HOST): '10.0.0.1' + env(SENTRY_DSN): "http://%env(HOST)%/project" + sentry: + dsn: '%env(resolve:SENTRY_DSN)%' ``env(csv:FOO)`` Decodes ``FOO`` that is a single row of comma seperated values +.. code-block:: php + + parameters: + env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2" + framework: + trusted_hosts: '%env(csv:TRUSTED_HOSTS)%' + ``env(file:FOO)`` Reads the contents of a file named in ``FOO`` + +.. code-block:: php + + parameters: + env(AUTH_FILE): "auth.json" + google: + auth: '%env(file:AUTH_FILE)%' It is also possible to combine the processors: ``env(json:file:FOO)`` Reads the contents of a file named in ``FOO``, and then decode it from json, resulting in an array or ``null`` +.. code-block:: php + + parameters: + env(AUTH_FILE): "%kernel.root%/auth.json" + google: + auth: '%env(file:resolve:AUTH_FILE)%' + .. _configuration-env-var-in-prod: From e3fe5fe4fff8466cbb2c4edc917ae9f1c0bcdf5e Mon Sep 17 00:00:00 2001 From: Fred Cox Date: Thu, 24 May 2018 20:35:11 +0300 Subject: [PATCH 3/4] Example of customer env var processor --- configuration/external_parameters.rst | 34 +++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst index 147612d4731..16fb8013793 100644 --- a/configuration/external_parameters.rst +++ b/configuration/external_parameters.rst @@ -237,6 +237,40 @@ It is also possible to combine the processors: auth: '%env(file:resolve:AUTH_FILE)%' +Custom Environment Variable Processors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Its possible to add further processors for environment variables. You just need +to add an implementation of `Symfony\Component\DependencyInjection\EnvVarProcessorInterface`. + +.. code-block:: php + + class LowercasingEnvVarProcessor implements EnvVarProcessorInterface + { + private $container; + + public function __construct(ContainerInterface $container) + { + $this->container = $container; + } + + public function getEnv($prefix, $name, \Closure $getEnv) + { + $env = $getEnv($name); + + return strtolower($env); + } + + public static function getProvidedTypes() + { + return [ + 'lowercase' => 'string', + ]; + } + } + + + .. _configuration-env-var-in-prod: Configuring Environment Variables in Production From aed16071650ac591d0a71c3b806106671090ca09 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 25 May 2018 20:58:41 +0200 Subject: [PATCH 4/4] Minor rewords and formatting fixes --- configuration/external_parameters.rst | 135 +++++++++++++------------- 1 file changed, 69 insertions(+), 66 deletions(-) diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst index 16fb8013793..6666aec4f2f 100644 --- a/configuration/external_parameters.rst +++ b/configuration/external_parameters.rst @@ -102,8 +102,11 @@ will be used whenever the corresponding environment variable is *not* found: Environment Variable Processors ------------------------------- -When using environment variables they are always strings by default, but sometimes -you will want to have specific types so that they match the types expected by your code. +The values of the environment variables are considered strings by default. +However, your code may expect other data types, like integers or booleans. +Symfony solves this problem with *processors*, which modify the contents of the +given environment variables. The following example uses the integer processor to +turn the value of the ``HTTP_PORT`` env var into an integer: .. configuration-block:: @@ -141,109 +144,111 @@ you will want to have specific types so that they match the types expected by yo ) )); -A number of different types are supported: +Symfony provides the following env var processors: ``env(string:FOO)`` - Casts ``FOO`` to a string + Casts ``FOO`` to a string: -.. code-block:: php + .. code-block:: yaml - parameters: - env(SECRET): "some_secret" - framework: - secret: '%env(string:SECRET)%' + parameters: + env(SECRET): "some_secret" + framework: + secret: '%env(string:SECRET)%' ``env(bool:FOO)`` - Casts ``FOO`` to a bool + Casts ``FOO`` to a bool: -.. code-block:: php + .. code-block:: yaml - parameters: - env(HTTP_METHOD_OVERRIDE): "true" - framework: - http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%' + parameters: + env(HTTP_METHOD_OVERRIDE): "true" + framework: + http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%' ``env(int:FOO)`` - Casts ``FOO`` to an int + Casts ``FOO`` to an int. ``env(float:FOO)`` - Casts ``FOO`` to an float + Casts ``FOO`` to an float. ``env(const:FOO)`` - Finds the const value named in ``FOO`` + Finds the const value named in ``FOO``: -.. code-block:: php + .. code-block:: yaml - parameters: - env(HEALTH_CHECK_METHOD): "Symfony\Component\HttpFoundation\Request:METHOD_HEAD" - security: - access_control: - - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' } + parameters: + env(HEALTH_CHECK_METHOD): "Symfony\Component\HttpFoundation\Request:METHOD_HEAD" + security: + access_control: + - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' } ``env(base64:FOO)`` - Decodes ``FOO`` that is a base64 encoded string - + Decodes the content of ``FOO``, which is a base64 encoded string. + ``env(json:FOO)`` - Decodes ``FOO`` that is a json encoded string into either an array or ``null`` + Decodes the content of ``FOO``, which is a JSON encoded string. It returns + either an array or ``null``: -.. code-block:: php + .. code-block:: yaml + + parameters: + env(TRUSTED_HOSTS): "['10.0.0.1', '10.0.0.2']" + framework: + trusted_hosts: '%env(json:TRUSTED_HOSTS)%' - parameters: - env(TRUSTED_HOSTS): "['10.0.0.1', '10.0.0.2']" - framework: - trusted_hosts: '%env(json:TRUSTED_HOSTS)%' - ``env(resolve:FOO)`` - Resolves references in the string ``FOO`` to other parameters + Replaces the string ``FOO`` by the value of a config parameter with the + same name: -.. code-block:: php + .. code-block:: yaml - parameters: - env(HOST): '10.0.0.1' - env(SENTRY_DSN): "http://%env(HOST)%/project" - sentry: - dsn: '%env(resolve:SENTRY_DSN)%' + parameters: + env(HOST): '10.0.0.1' + env(SENTRY_DSN): "http://%env(HOST)%/project" + sentry: + dsn: '%env(resolve:SENTRY_DSN)%' ``env(csv:FOO)`` - Decodes ``FOO`` that is a single row of comma seperated values + Decodes the content of ``FOO``, which is a CSV-encoded string: -.. code-block:: php + .. code-block:: yaml - parameters: - env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2" - framework: - trusted_hosts: '%env(csv:TRUSTED_HOSTS)%' + parameters: + env(TRUSTED_HOSTS): "10.0.0.1, 10.0.0.2" + framework: + trusted_hosts: '%env(csv:TRUSTED_HOSTS)%' ``env(file:FOO)`` - Reads the contents of a file named in ``FOO`` + Returns the contents of a file whose path is the value of the ``FOO`` env var: -.. code-block:: php + .. code-block:: yaml - parameters: - env(AUTH_FILE): "auth.json" - google: - auth: '%env(file:AUTH_FILE)%' - -It is also possible to combine the processors: + parameters: + env(AUTH_FILE): "../config/auth.json" + google: + auth: '%env(file:AUTH_FILE)%' -``env(json:file:FOO)`` - Reads the contents of a file named in ``FOO``, and then decode it from json, resulting in an array or ``null`` +It is also possible to combine any number of processors: -.. code-block:: php +.. code-block:: yaml parameters: - env(AUTH_FILE): "%kernel.root%/auth.json" + env(AUTH_FILE): "%kernel.project_dir%/config/auth.json" google: - auth: '%env(file:resolve:AUTH_FILE)%' - + # 1. gets the value of the AUTH_FILE env var + # 2. replaces the values of any config param to get the config path + # 3. gets the content of the file stored in that path + # 4. JSON-decodes the content of the file and returns it + auth: '%env(json:file:resolve:AUTH_FILE)%' Custom Environment Variable Processors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Its possible to add further processors for environment variables. You just need -to add an implementation of `Symfony\Component\DependencyInjection\EnvVarProcessorInterface`. - -.. code-block:: php +It's also possible to add your own processors for environment variables. First, +create a class that implements +:class:`Symfony\\Component\\DependencyInjection\\EnvVarProcessorInterface` and +then, define a service for that class:: class LowercasingEnvVarProcessor implements EnvVarProcessorInterface { @@ -269,8 +274,6 @@ to add an implementation of `Symfony\Component\DependencyInjection\EnvVarProcess } } - - .. _configuration-env-var-in-prod: Configuring Environment Variables in Production