环境变量处理器

编辑此页

使用环境变量配置 Symfony 应用程序 是一种常见的实践，使你的应用程序真正动态化。

环境变量的主要问题是它们的值只能是字符串，而你的应用程序可能需要其他数据类型（整数、布尔值等）。Symfony 通过“环境变量处理器”解决了这个问题，它可以转换给定环境变量的原始内容。以下示例使用 integer 处理器将 HTTP_PORT 环境变量的值转换为整数

1
2
3
4
# config/packages/framework.yaml
framework:
    router:
        http_port: '%env(int:HTTP_PORT)%'

内置环境变量处理器

Symfony 提供了以下环境变量处理器

env(string:FOO)

将 FOO 转换为字符串

1
2
3
4
5
# config/packages/framework.yaml
parameters:
    env(SECRET): 'some_secret'
framework:
    secret: '%env(string:SECRET)%'
env(bool:FOO)

将 FOO 转换为布尔值（true 值包括 'true'、'on'、'yes'、除 0 和 0.0 之外的所有数字以及除 '0' 和 '0.0' 之外的所有数字字符串；其他所有值均为 false）

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)

将 FOO 转换为布尔值（与 env(bool:...) 的作用相同），但返回相反的值（假值返回为 true，真值返回为 false）

1
2
3
# config/services.yaml
parameters:
    safe_for_production: '%env(not:APP_DEBUG)%'
env(int:FOO)
将 FOO 转换为整数。
env(float:FOO)
将 FOO 转换为浮点数。
env(const:FOO)

查找在 FOO 中命名的常量值

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)
解码 FOO 的内容，它是一个 base64 编码的字符串。
env(json:FOO)

解码 FOO 的内容，它是一个 JSON 编码的字符串。它返回一个数组或 null

1
2
3
4
# config/packages/framework.yaml
parameters:
    env(ALLOWED_LANGUAGES): '["en","de","es"]'
    app_allowed_languages: '%env(json:ALLOWED_LANGUAGES)%'
env(resolve:FOO)

如果 FOO 的内容包含容器参数（使用 %parameter_name% 语法），它会将参数替换为它们的值

1
2
3
4
5
6
# config/packages/sentry.yaml
parameters:
    sentry_host: '10.0.0.1'
    env(SENTRY_DSN): 'http://%sentry_host%/project'
sentry:
    dsn: '%env(resolve:SENTRY_DSN)%'
env(csv:FOO)

解码 FOO 的内容，它是一个 CSV 编码的字符串

1
2
3
4
# config/packages/framework.yaml
parameters:
    env(ALLOWED_LANGUAGES): "en,de,es"
    app_allowed_languages: '%env(csv:ALLOWED_LANGUAGES)%'
env(shuffle:FOO)

随机打乱 FOO 环境变量的值，它必须是一个数组。

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)%"]
env(file:FOO)

返回路径为 FOO 环境变量的值的文件内容

1
2
3
4
5
# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): '%kernel.project_dir%/config/auth.json'
google:
    auth: '%env(file:AUTH_FILE)%'
env(require:FOO)

require() 路径为 FOO 环境变量的值的 PHP 文件，并返回它返回的值。

1
2
3
4
5
# config/packages/framework.yaml
parameters:
    env(PHP_FILE): '%kernel.project_dir%/config/.runtime-evaluated.php'
app:
    auth: '%env(require:PHP_FILE)%'
env(trim:FOO)

修剪 FOO 环境变量的内容，删除字符串开头和结尾的空格。这与 file 处理器结合使用特别有用，因为它会删除文件末尾的换行符。

1
2
3
4
5
# config/packages/framework.yaml
parameters:
    env(AUTH_FILE): '%kernel.project_dir%/config/auth.json'
google:
    auth: '%env(trim:file:AUTH_FILE)%'
env(key:FOO:BAR)

从 BAR 环境变量中存储的数组内容中检索与键 FOO 关联的值

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)

当 BAR 环境变量不可用时，检索参数 fallback_param 的值

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)%'

当省略回退参数时（例如 env(default::API_KEY)），则返回的值为 null。

env(url:FOO)

解析绝对 URL 并将其组件作为关联数组返回。

1
2
# .env
MONGODB_URL="mongodb://db_user:[email protected]:27017/db_name"
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)%'

警告

为了方便从 URL 中提取资源，前导 / 从 path 组件中删除。

env(query_string:FOO)

解析给定 URL 的查询字符串部分，并将其组件作为关联数组返回。

1
2
# .env
MONGODB_URL="mongodb://db_user:[email protected]:27017/db_name?timeout=3000"
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)

尝试将环境变量转换为实际的 \BackedEnum 值。此处理器将 \BackedEnum 的完全限定名称作为参数

1
2
3
4
5
6
7
8
// App\Enum\Suit.php
enum Suit: string
{
    case Clubs = 'clubs';
    case Spades = 'spades';
    case Diamonds = 'diamonds';
    case Hearts = 'hearts';
}
1
2
3
# config/services.yaml
parameters:
    suit: '%env(enum:App\Enum\Suit:CARD_SUIT)%'

存储在 CARD_SUIT 环境变量中的值将是一个字符串（例如 'spades'），但应用程序将使用枚举值（例如 Suit::Spades）。

env(defined:NO_FOO)

如果 env 变量存在且其值不是 ''（空字符串）或 null，则评估为 true；否则返回 false。

1
2
3
# config/services.yaml
parameters:
    typed_env: '%env(defined:FOO)%'
env(urlencode:FOO)

使用 urlencode PHP 函数对 FOO 环境变量的内容进行编码。当 FOO 值与 DSN 语法不兼容时，这尤其有用。

1
2
3
4
# config/packages/framework.yaml
parameters:
    env(DATABASE_URL): 'mysql://db_user:foo@[email protected]:3306/db_name'
    encoded_database_url: '%env(urlencode:DATABASE_URL)%'

7.1

env(urlencode:...) 环境变量处理器在 Symfony 7.1 中引入。

也可以组合任意数量的处理器

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)%'

自定义环境变量处理器

也可以为环境变量添加你自己的处理器。首先，创建一个实现 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): string
    {
        $env = $getEnv($name);

        return strtolower($env);
    }

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

要在应用程序中启用新的处理器，请将其注册为服务，并使用 container.env_var_processor 标签对其进行标记。如果你正在使用默认的 services.yaml 配置，由于 自动配置，这已经为你完成。

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。
目录
    版本