PHP dotenv

自动将环境变量从 .env 加载到 getenv()、$_ENV 和 $_SERVER。

为什么使用 .env？

你永远不应该在代码中存储敏感凭据。在环境中存储配置是十二要素应用的原则之一。任何在部署环境之间可能发生变化的内容 - 比如数据库凭据或第三方服务的凭据 - 都应该从代码中提取到环境变量中。

基本上，.env 文件是一种简单的方式来加载应用程序需要的自定义配置变量，而无需修改 .htaccess 文件或 Apache/nginx 虚拟主机。这意味着你不需要编辑项目外的任何文件，无论你如何运行项目 - Apache、Nginx、CLI，甚至是 PHP 的内置 Web 服务器 - 所有环境变量都会被设置。它比你所知道的设置环境变量的其他方式都要简单得多，你一定会喜欢上它！

无需编辑 Apache 或 Nginx 中的虚拟主机
无需在 .htaccess 文件中添加 php_value 标志
轻松实现所需 ENV 值的可移植性和共享
兼容 PHP 的内置 Web 服务器和 CLI 运行器

PHP dotenv 是原始 Ruby dotenv 的 PHP 版本。

安装

通过 Composer 安装非常简单：

$ composer require vlucas/phpdotenv

或者手动将其添加到你的 composer.json 文件中。

升级

我们遵循语义化版本控制，这意味着主要版本之间可能会出现破坏性变更。我们提供了从 V2 到 V3、V3 到 V4 以及 V4 到 V5 的升级指南，可以在这里找到。

使用方法

.env 文件通常不纳入版本控制，因为它可能包含敏感的 API 密钥和密码。创建一个单独的 .env.example 文件，其中定义了所有必需的环境变量，除了敏感的变量。这些敏感变量要么由用户为自己的开发环境提供，要么通过其他方式与项目合作者沟通。然后，项目合作者独立地将 .env.example 文件复制到本地的 .env 文件，并确保所有设置对他们的本地环境都是正确的，在必要时填写秘密密钥或提供自己的值。在这种用法中，.env 文件应该添加到项目的 .gitignore 文件中，以确保它永远不会被合作者提交。这种用法确保没有敏感的密码或 API 密钥会出现在版本控制历史中，从而降低安全漏洞的风险，而且生产环境的值永远不需要与所有项目合作者共享。

将你的应用程序配置添加到项目根目录的 .env 文件中。确保将 .env 文件添加到 .gitignore 中，这样它就不会被检入代码

S3_BUCKET="dotenv"
SECRET_KEY="souper_seekret_key"

现在创建一个名为 .env.example 的文件并将其检入项目。这个文件应该包含你需要设置的 ENV 变量，但值应该为空或填充虚拟数据。这样做的目的是让人们知道需要哪些变量，但不给他们敏感的生产值。

S3_BUCKET="devbucket"
SECRET_KEY="abc123"

然后你可以在应用程序中这样加载 .env：

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

如果想要抑制在没有 .env 文件时抛出的异常，你可以：

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->safeLoad();

你也可以将文件名作为第二个参数传入，如果你想使用 .env 以外的其他文件：

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, 'myconfig');
$dotenv->load();

所有定义的变量现在都可以在 $_ENV 和 $_SERVER 超全局变量中使用。

$s3_bucket = $_ENV['S3_BUCKET'];
$s3_bucket = $_SERVER['S3_BUCKET'];

Putenv 和 Getenv

由于 getenv() 和 putenv() 这些函数不是线程安全的，因此强烈建议不要使用它们，但仍然可以指示 PHP dotenv 使用这些函数。不调用 Dotenv::createImmutable，而是可以调用 Dotenv::createUnsafeImmutable，它会在后台添加 PutenvAdapter。现在你的环境变量可以使用 getenv 方法以及超全局变量来访问：

$s3_bucket = getenv('S3_BUCKET');
$s3_bucket = $_ENV['S3_BUCKET'];
$s3_bucket = $_SERVER['S3_BUCKET'];

嵌套变量

可以在另一个环境变量中嵌套一个环境变量，这有助于减少重复。

这是通过将现有环境变量包装在 ${…} 中实现的，例如：

BASE_DIR="/var/webroot/project-root"
CACHE_DIR="${BASE_DIR}/cache"
TMP_DIR="${BASE_DIR}/tmp"

不可变性和仓库自定义

不可变性指的是 Dotenv 是否允许覆盖现有的环境变量。如果你希望 Dotenv 覆盖现有的环境变量，请使用 createMutable 而不是 createImmutable：

$dotenv = Dotenv\Dotenv::createMutable(__DIR__);
$dotenv->load();

在背后，这是在指示"仓库"是否允许不可变性。默认情况下，仓库配置为允许覆盖现有值，这与使用 RepositoryBuilder 调用"create"方法来构建更自定义的仓库有关：

$repository = Dotenv\Repository\RepositoryBuilder::createWithNoAdapters()
    ->addAdapter(Dotenv\Repository\Adapter\EnvConstAdapter::class)
    ->addWriter(Dotenv\Repository\Adapter\PutenvAdapter::class)
    ->immutable()
    ->make();

$dotenv = Dotenv\Dotenv::create($repository, __DIR__);
$dotenv->load();

上面的例子将把加载的值写入 $_ENV 和 putenv，但在插值环境变量时，我们只会从 $_ENV 读取。此外，它永远不会替换在加载文件之前已经设置的任何变量。

通过另一个例子，还可以指定一组允许列表的变量。也就是说，只有允许列表中的变量才会被加载：

$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()
    ->allowList(['FOO', 'BAR'])
    ->make();

$dotenv = Dotenv\Dotenv::create($repository, __DIR__);
$dotenv->load();

要求设置变量

PHP dotenv 内置了验证功能，包括强制存在环境变量。这对于让人们知道你的应用程序如果没有这些显式要求的变量就无法工作特别有用。

你可以使用单个字符串：

$dotenv->required('DATABASE_DSN');

或者一个字符串数组：

$dotenv->required(['DB_HOST', 'DB_NAME', 'DB_USER', 'DB_PASS']);

如果缺少任何 ENV 变量，Dotenv 将抛出一个 RuntimeException，如下所示：

One or more environment variables failed assertions: DATABASE_DSN is missing

空变量

除了简单地要求设置变量外，你可能还需要确保变量不为空：

$dotenv->required('DATABASE_DSN')->notEmpty();

如果环境变量为空，你会得到一个异常：

One or more environment variables failed assertions: DATABASE_DSN is empty

整数变量

你可能还需要确保变量是整数值。你可以这样做：

$dotenv->required('FOO')->isInteger();

如果环境变量不是整数，你会得到一个异常：

One or more environment variables failed assertions: FOO is not an integer.

有时你可能只想在变量设置时强制执行验证规则。我们也支持这一点：

$dotenv->ifPresent('FOO')->isInteger();

布尔变量

你可能需要确保变量是布尔形式的，接受 "true"、"false"、"On"、"1"、"Yes"、"Off"、"0" 和 "No"。你可以这样做：

$dotenv->required('FOO')->isBoolean();

如果环境变量不是布尔值，你会得到一个异常：

One or more environment variables failed assertions: FOO is not a boolean.

同样，你可以写：

$dotenv->ifPresent('FOO')->isBoolean();

允许的值

还可以定义环境变量应该具有的一组值。这在只有少数选项或驱动程序实际上被你的代码支持的情况下特别有用：

$dotenv->required('SESSION_STORE')->allowedValues(['Filesystem', 'Memcached']);

如果环境变量不在这个允许的值列表中，你会得到一个类似的异常：

One or more environment variables failed assertions: SESSION_STORE is not an allowed value.

也可以定义环境变量应该匹配的正则表达式。

$dotenv->required('FOO')->allowedRegexValues('([[:lower:]]{3})');

注释

你可以使用 # 字符在 .env 文件中添加注释。例如：

# 这是一条注释
VAR="value" # 注释
VAR=value # 注释

解析而不加载

有时你只想解析文件并解析嵌套的环境变量，通过给我们一个字符串，并返回一个数组给你。虽然这已经是可能的，但有点麻烦，所以我们提供了一种直接的方法来做到这一点：

// ['FOO' => 'Bar', 'BAZ' => 'Hello Bar']
Dotenv\Dotenv::parse("FOO=Bar\nBAZ=\"Hello \${FOO}\"");

这与以下操作完全相同：

Dotenv\Dotenv::createArrayBacked(__DIR__)->load();

只是，你不是提供目录来查找文件，而是直接提供了文件内容。

使用注意事项

当新开发人员克隆你的代码库时，他们将有一个额外的一次性步骤，手动将 .env.example 文件复制到 .env 并填写他们自己的值（或从项目同事那里获取任何敏感值）。

故障排除

在某些服务器设置中（最常见于共享主机），PHP 可能会禁用像 $_ENV 或 $_SERVER 这样的超全局变量。如果这些变量没有设置，请检查 php.ini 文件中的 variables_order。参见 php.net/manual/en/ini.core.php#ini.variables-order。