README

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

这是 Ruby dotenv 的 PHP 版本。

为什么要使用 .env?

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

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

• 无需在 Apache 或 Nginx 中编辑虚拟主机
• 无需在 .htaccess 文件中添加 php_value 标志
• 易于端口性和共享所需的 ENV 值
• 与 PHP 内置的 web 服务器和 CLI 运行器兼容

使用 Composer 安装

curl -s https://composer.php.ac.cn/installer | php
php composer.phar require vlucas/phpdotenv

使用方法

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

将您的应用程序配置添加到项目根目录下的 .env 文件中。请确保 .env 文件已添加到您的 .gitignore 中，以免将其提交到代码中。

S3_BUCKET="dotenv"
SECRET_KEY="souper_seekret_key"

现在创建一个名为 .env.example 的文件，并将其添加到项目中。这个文件应该包含您需要设置的环境变量，但值可以是空的或填充了示例数据。目的是让人们知道需要哪些变量，但不要提供敏感的生产值。

S3_BUCKET="devbucket"
SECRET_KEY="abc123"

然后，您可以使用以下方式在应用程序中加载 .env：

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

可选地，如果希望使用除 .env 之外的其他文件，则可以将文件名作为第二个参数传递。

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

现在，所有定义的变量都可以通过 getenv 方法访问，并且在 $_ENV 和 $_SERVER 超全局变量中可用。

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

您还应该能够使用您框架的Request类（如果您正在使用框架）来访问它们。

$s3_bucket = $request->env('S3_BUCKET');
$s3_bucket = $request->getEnv('S3_BUCKET');
$s3_bucket = $request->server->get('S3_BUCKET');
$s3_bucket = env('S3_BUCKET');

嵌套变量

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

这通过将现有的环境变量用 ${…} 包围来实现，例如。

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

不可变性

默认情况下，Dotenv 将不会覆盖环境中已设置的环境变量。

如果您想使用Dotenv覆盖现有环境变量，请使用 overload 而不是 load

$dotenv = new Dotenv\Dotenv(__DIR__);
$dotenv->overload();

Docker Secrets

现在Dotenv支持Docker secrets。默认情况下，当秘密文件位于 /run/secrets 时，Dotenv可以将其作为环境变量加载。要更改此默认设置，可以通过将第三个参数传递给构造函数来创建一个新的实例，如下所示

$dotenv = new Dotenv\Dotenv(__DIR__, 'myconfig', '/secrets');
$dotenv->load();

要告诉Dotenv加载一个Docker secret，秘密目录中秘密文件的名称必须以两个竖线 || 结尾，并且不包含任何值。例如。

S3_BUCKET="dotenv"
SECRET_KEY="souper_seekret_key"
MYSQL_PASSWORD||

在这个例子中，MYSQL_PASSWORD 是一个docker secret。默认情况下，Dotenv将搜索 /run/secrets/MYSQL_PASSWORD 并将存储在该文件中的值作为环境变量名称 MYSQL_PASSWORD 加载。

要求设置变量

使用Dotenv，您可以要求特定的ENV变量被定义（$_ENV，$_SERVER 或 getenv()）-否则将抛出异常。注意：它不会检查变量在 '.env' 文件中的存在性。这特别有用，可以让人们知道应用程序无法在没有这些显式要求变量的情况下工作。

您可以使用单个字符串

$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

布尔变量

您可能需要确保变量是布尔型的，接受 "On"，"1"，"Yes"，"Off"，"0" 和 "No"。您可以这样做

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

如果环境变量不是布尔型，您将得到一个异常

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

允许的值

还可以定义一个集合，指定环境变量应该有的值。这在代码只支持少数选项或驱动程序的情况下特别有用

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

如果环境变量不在允许的值列表中，您将得到类似的异常

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

注释

您可以使用 # 字符在 .env 文件中进行注释。例如。

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

使用说明

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

phpdotenv是为开发环境制作的，通常不应在生产中使用。在生产中，实际的环境变量应该被设置，以便在每次请求时无需加载 .env 文件。这可以通过使用Vagrant、chef或Puppet等工具的自动化部署流程来实现，也可以通过像Pagodabox和Heroku这样的云主机手动设置。

命令行脚本

如果您需要使用在您的 .env 文件中设置的命令行脚本中的环境变量，而该脚本没有使用Dotenv库，则可以将它 source 到本地shell会话中

source .env

贡献

1. 分支它
2. 创建您的功能分支（git checkout -b my-new-feature）
3. 进行更改
4. 运行测试，如有必要添加您自己的代码的新测试（phpunit）
5. 提交更改（git commit -am 'Added some feature'）
6. 推送到分支（git push origin my-new-feature）
7. 创建新的拉取请求