Environment Variable Processors

Using env vars to configure Symfony applications is a common practice to make your applications truly dynamic.

環境変数を使用して Symfony アプリケーションを構成することは、アプリケーションを真に動的にするための一般的な方法です。

The main issue of env vars is that their values can only be strings and your application may need other data types (integer, boolean, etc.). Symfony solves this problem with "env var processors", which transform the original 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:

環境変数の主な問題は、それらの値が文字列のみであり、アプリケーションが他のデータ型 (整数、ブール値など) を必要とする場合があることです。 symfony は、与えられた環境変数の元の内容を変換する「env var プロセッサ」でこの問題を解決します。次の例では、integerprocessor を使用して、HTTP_PORT 環境変数の値を整数に変換しています。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
 
# config/packages/framework.yaml
framework:
    router:
        http_port: '%env(int:HTTP_PORT)%'

Built-In Environment Variable Processors

Symfony provides the following env var processors:

Symfony は以下の env var プロセッサーを提供します:
env(string:FOO)

Casts FOO to a string:

FOO を文字列にキャストします。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(SECRET): 'some_secret'
framework:
    secret: '%env(string:SECRET)%'
env(bool:FOO)

Casts FOO to a bool (true values are 'true', 'on', 'yes' and all numbers except 0 and 0.0; everything else is false):

FOO を bool にキャストします (真の値は 'true'、'on'、'yes'、および 0 と 0.0 を除くすべての数値で、それ以外はすべて false):
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(HTTP_METHOD_OVERRIDE): 'true'
framework:
    http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'
env(not:FOO)

Casts FOO to a bool (just as env(bool:...) does) except it returns the inverted value (falsy values are returned as true, truthy values are returned as false):

FOO を bool にキャストします (env(bool:...) と同じように) が、逆の値を返すことを除きます (偽の値は true として返され、真の値は false として返されます)。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
 
# config/services.yaml
parameters:
    safe_for_production: '%env(not:APP_DEBUG)%'
env(int:FOO)
Casts FOO to an int.
FOO を int にキャストします。
env(float:FOO)
Casts FOO to a float.
FOO を float にキャストします。
env(const:FOO)

Finds the const value named in FOO:

FOO で指定された const 値を検索します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
 
# config/packages/security.yaml
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 the content of FOO, which is a base64 encoded string.
base64 でエンコードされた文字列である FOO の内容をデコードします。
env(json:FOO)

Decodes the content of FOO, which is a JSON encoded string. It returns either an array or null:

JSON でエンコードされた文字列である FOO の内容をデコードします。配列または null のいずれかを返します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(TRUSTED_HOSTS): '["10.0.0.1", "10.0.0.2"]'
framework:
    trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
env(resolve:FOO)

If the content of FOO includes container parameters (with the syntax %parameter_name%), it replaces the parameters by their values:

FOO のコンテンツにコンテナー パラメーター (構文 %parameter_name% を使用) が含まれている場合、パラメーターはその値で置き換えられます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
 
# config/packages/sentry.yaml
parameters:
    env(HOST): '10.0.0.1'
    sentry_host: '%env(HOST)%'
    env(SENTRY_DSN): 'http://%sentry_host%/project'
sentry:
    dsn: '%env(resolve:SENTRY_DSN)%'
env(csv:FOO)

Decodes the content of FOO, which is a CSV-encoded string:

CSV エンコードされた文字列である FOO の内容をデコードします。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(TRUSTED_HOSTS): "10.0.0.1,10.0.0.2"
framework:
   trusted_hosts: '%env(csv:TRUSTED_HOSTS)%'
env(shuffle:FOO)

Randomly shuffles values of the FOO env var, which must be an array.

配列でなければならない FOO 環境変数の値をランダムにシャッフルします。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
 
# config/packages/framework.yaml
parameters:
    env(REDIS_NODES): "127.0.0.1:6380,127.0.0.1:6381"
services:
    RedisCluster:
        class: RedisCluster
        arguments: [null, "%env(shuffle:csv:REDIS_NODES)%"]

6.2

6.2

The env(shuffle:...) env var processor was introduced in Symfony 6.2.

env(shuffle:...) env var プロセッサは Symfony 6.2 で導入されました。
env(file:FOO)

Returns the contents of a file whose path is the value of the FOO env var:

パスが FOO 環境変数の値であるファイルの内容を返します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): '../config/auth.json'
google:
    auth: '%env(file:AUTH_FILE)%'
env(require:FOO)

require() the PHP file whose path is the value of the FOO env var and return the value returned from it.

パスが FOOenv var の値である PHP ファイルを require() し、そこから返された値を返します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(PHP_FILE): '../config/.runtime-evaluated.php'
app:
    auth: '%env(require:PHP_FILE)%'
env(trim:FOO)

Trims the content of FOO env var, removing whitespaces from the beginning and end of the string. This is especially useful in combination with the file processor, as it'll remove newlines at the end of a file.

文字列の先頭と末尾から空白を削除して、FOO env var の内容をトリムします。これは、ファイルの末尾にある改行を削除するため、ファイル プロセッサと組み合わせると特に便利です。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): '../config/auth.json'
google:
    auth: '%env(trim:file:AUTH_FILE)%'
env(key:FOO:BAR)

Retrieves the value associated with the key FOO from the array whose contents are stored in the BAR env var:

内容が BAR 環境変数に格納されている配列から、キー FOO に関連付けられた値を取得します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/services.yaml
parameters:
    env(SECRETS_FILE): '/opt/application/.secrets.json'
    database_password: '%env(key:database_password:json:file:SECRETS_FILE)%'
    # if SECRETS_FILE contents are: {"database_password": "secret"} it returns "secret"
env(default:fallback_param:BAR)

Retrieves the value of the parameter fallback_param when the BAR env var is not available:

BAR envvar が利用できない場合、パラメーター fallback_param の値を取得します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/services.yaml
parameters:
    # if PRIVATE_KEY is not a valid file path, the content of raw_key is returned
    private_key: '%env(default:raw_key:file:PRIVATE_KEY)%'
    raw_key: '%env(PRIVATE_KEY)%'

When the fallback parameter is omitted (e.g. env(default::API_KEY)), then the returned value is null.

フォールバック パラメーターを省略した場合 (例: env(default::API_KEY))、返される値は null です。
env(url:FOO)

Parses an absolute URL and returns its components as an associative array.

絶対 URL を解析し、そのコンポーネントを連想配列として返します。
1
2
 
# .env
MONGODB_URL="mongodb://db_user:db_password@127.0.0.1:27017/db_name"
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
10
11
 
# config/packages/mongodb.yaml
mongo_db_bundle:
    clients:
        default:
            hosts:
                - { host: '%env(string:key:host:url:MONGODB_URL)%', port: '%env(int:key:port:url:MONGODB_URL)%' }
            username: '%env(string:key:user:url:MONGODB_URL)%'
            password: '%env(string:key:pass:url:MONGODB_URL)%'
    connections:
        default:
            database_name: '%env(key:path:url:MONGODB_URL)%'

Caution

注意

In order to ease extraction of the resource from the URL, the leading / is trimmed from the path component.

URL からのリソースの抽出を容易にするために、先頭の / はパス コンポーネントから削除されます。
env(query_string:FOO)

Parses the query string part of the given URL and returns its components as an associative array.

指定された URL のクエリ文字列部分を解析し、そのコンポーネントを連想配列として返します。
1
2
 
# .env
MONGODB_URL="mongodb://db_user:db_password@127.0.0.1:27017/db_name?timeout=3000"
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
 
# config/packages/mongodb.yaml
mongo_db_bundle:
    clients:
        default:
            # ...
            connectTimeoutMS: '%env(int:key:timeout:query_string:MONGODB_URL)%'
env(enum:FooEnum:BAR)

Tries to convert an environment variable to an actual \BackedEnum value. This processor takes the fully qualified name of the \BackedEnum as an argument.

環境変数を実際の \BackedEnum 値に変換しようとします。このプロセッサは、\BackedEnum の完全修飾名を引数として受け取ります。
1
2
3
4
5
6
 
# App\Enum\Environment
enum Environment: string
{
    case Development = 'dev';
    case Production = 'prod';
}
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
 
# config/services.yaml
parameters:
    typed_env: '%env(enum:App\Enum\Environment:APP_ENV)%'

6.2

6.2

The env(enum:...) env var processor was introduced in Symfony 6.2.

env(enum:...) env var プロセッサは Symfony 6.2 で導入されました。

It is also possible to combine any number of processors:

任意の数のプロセッサを組み合わせることもできます。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
7
8
9
 
# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): "%kernel.project_dir%/config/auth.json"
google:
    # 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

It's also possible to add your own processors for environment variables. First, create a class that implements EnvVarProcessorInterface:

環境変数用に独自のプロセッサを追加することもできます。まず、EnvVarProcessorInterface を実装するクラスを作成します。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
use Symfony\Component\DependencyInjection\EnvVarProcessorInterface;

class LowercasingEnvVarProcessor implements EnvVarProcessorInterface
{
    public function getEnv(string $prefix, string $name, \Closure $getEnv)
    {
        $env = $getEnv($name);

        return strtolower($env);
    }

    public static function getProvidedTypes()
    {
        return [
            'lowercase' => 'string',
        ];
    }
}

To enable the new processor in the app, register it as a service and tag it with the container.env_var_processor tag. If you're using the default services.yaml configuration, this is already done for you, thanks to autoconfiguration.

アプリで新しいプロセッサを有効にするには、それをサービスとして登録し、container.env_var_processortag でタグ付けします。デフォルトの services.yaml 構成を使用している場合、自動構成のおかげで、これは既に行われています。