Project Icon

phpdotenv

PHP环境变量管理库 轻松加载配置信息

phpdotenv是一个强大的PHP环境变量管理库,可从.env文件自动加载配置到系统环境中。它支持变量嵌套、验证和安全加载,适用于多种PHP环境。该库简化了配置管理,有效分离敏感信息,增强了项目安全性和可移植性。phpdotenv为PHP开发者提供了一种简单而灵活的方式来处理项目配置。

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

上面的例子将把加载的值写入 $_ENVputenv,但在插值环境变量时,我们只会从 $_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

安全性

如果你在此软件包中发现安全漏洞,请发送电子邮件至 security@tidelift.com。我们将立即处理所有安全漏洞。你可以在这里查看我们的完整安全政策。

许可证

PHP dotenv 根据 BSD 3-Clause 许可证 授权。

企业版

作为 Tidelift 订阅的一部分提供

vlucas/phpdotenv 的维护者以及数千个其他软件包的维护者正在

项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手,通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能,支持100+编程语言,与主流编辑器无缝集成,显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台,能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐,Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案,通过智能技术简化视频制作流程。无论是企业宣传还是个人分享,有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持,能够阅读和理解用户上传的文件内容,解析网页信息,并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题,Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术,为商家提供一键生成商品图和营销文案的服务,显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台,让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型,免费访问各种图像生成与AI训练工具,从Stable Diffusion等基础模型开始,轻松实现创新图像生成。体验前沿的AI技术,推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器,它将改变您观看视频的方式!SubCat结合了先进的人工智能技术,为您提供即时视频字幕翻译,无论是本地视频还是网络流媒体,让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台,利用前沿AI技术,为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图,再到文案生成,美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具,简化了选题、文献检索至论文撰写的整个过程。通过简单设定,平台可快速生成高质量论文大纲和全文,配合图表、参考文献等一应俱全,同时提供开题报告和答辩PPT等增值服务,保障数据安全,有效提升写作效率和论文质量。

投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号