README

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

为什么使用 .env？

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

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

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

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

使用 Composer 安装

通过 Composer 安装非常简单

$ composer require vlucas/phpdotenv

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

使用方法

由于可能包含敏感的 API 密钥和密码，因此通常将 .env 文件排除在版本控制之外。创建一个名为 .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'];

如果您使用的是框架，您也应该能够通过您的框架的请求类访问它们。

$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

布尔变量

您可能需要确保变量是布尔形式，接受"开"、"1"、"是"、"关"、"0"和"否"。您可以这样做

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

命令行脚本

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

source .env

贡献

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

企业

作为Tidelift订阅的一部分提供

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

nielbuys / phpdotenv

维护者

详细信息