環境變數處理器

編輯此頁面

使用環境變數來設定 Symfony 應用程式 是一種常見的做法，可以使您的應用程式真正動態化。

環境變數的主要問題是它們的值只能是字串，而您的應用程式可能需要其他資料類型（整數、布林值等）。Symfony 使用「環境變數處理器」解決了這個問題，它可以轉換給定環境變數的原始內容。以下範例使用整數處理器將 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:...) 一樣），但會傳回反轉的值（falsy 值會傳回 true，truthy 值會傳回 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)%'

當省略 fallback 參數時（例如 env(default::API_KEY)），則傳回值為 null。

env(url:FOO)

解析絕對 URL 並將其組件作為關聯陣列傳回。

1
2
# .env
MONGODB_URL="mongodb://db_user:db_password@127.0.0.1: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:db_password@127.0.0.1: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)

如果環境變數存在且其值不是 ''（空字串）或 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@b$r@127.0.0.1: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 授權條款授權。
目錄
    版本