README

自动将环境变量从 .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 调用“创建”方法以构建更自定义的存储库时相关。

$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 文件中添加注释。例如。

# this is a comment
VAR="value" # comment
VAR=value # comment

解析而不加载

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

// ['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。

安全

如果您在此包中发现安全漏洞，请发送电子邮件至[email protected]。所有安全漏洞都将得到及时解决。您可以在此处查看我们的完整安全策略。

许可

PHP dotenv遵循BSD 3-Clause 许可协议。

企业版

作为Tidelift订阅的一部分提供

vlucas/phpdotenv维护者以及数千个其他包维护者正在与Tidelift合作，为您的应用程序构建过程中使用的开源依赖项提供商业支持和维护。节省时间，降低风险，并提高代码质量，同时支付您实际使用的依赖项维护者。了解更多信息：点击这里。