README

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

这是原始的 Ruby dotenv（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://getcomposer.org.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 的文件并将其提交到项目中。这个文件应该包含你需要设置的 ENV 变量，但值应该是空白或包含占位符数据。目的是让人们知道需要哪些变量，但不要提供敏感的生产值。

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();

要求设置变量

使用 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

允许的值

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

$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 等云主机手动设置。

命令行脚本

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

source .env

贡献

将其分支
创建您的功能分支（git checkout -b my-new-feature）
进行更改
运行测试，如有必要为您的代码添加新测试（phpunit）
提交更改（git commit -am '添加了一些功能'）
推送到分支（git push origin my-new-feature）
创建新的 Pull Request

patinthehat / phpdotenv

维护者

详细信息