[译] dotenv - PHP版本的 .env

原文地址:PHP dotenv

经过 .env 加载环境变量而且可以自动的经过 getenv(), $_ENV 和 $_SERVER 自动调用.

这是一个PHP版本 Ruby dotenv.

为何是 .env?

你不能在代码中存储任何的 敏感/帐号 数据. 存储 在环境中存储配置 是 12-factors的一项规则. 在部署中可能变化的全部的内容 – 诸如数据库认证或者第三方服务的认证应该从代码中剥离出来.也就是环境变量的概念.

广义上来讲, 一个 .env 文件是加载自定义配置的一个简单的方法, 这样你的应用不须要修改 .htaccess 文件或者 Apache/nginx 虚拟主机. 这意味着你不须要编辑项目以外的任何文件,而且全部的环境变量都配置完整了, 不管你运行在 Apache, Nginx, CLI 仍是 PHP 5.4 上内建的web服务器上. 这是一个所知的设置环境变量最简单的方法, 你会喜欢上它的.

• 无需在 Apache 或者 Nginx上额外配置虚拟主机配置

• 无需在 .htaccess 中添加 php_value 值

• 方便移植和共享 ENV 环境变量值

• 兼容服务器内置的服务器和 CLI 运行器

使用 composer 安装

curl -s http://getcomposer.org/installer | php
php composer.phar require vlucas/phpdotenv

使用方法

---

.env 文件一般不包含在版本控制内, 它可能包含敏感的 API Key 或者 密码. 全部须要环境变量定义(不敏感的定义)的项目都须要建立一个 .env.example 文件, 这个环境变量包含他们本身定义的环境变量或者联合开发包含的环境变量. 项目合做开发者能够独立的复制 .env.example 而且重命名为 .env , 而且修改成正确的本地环境配置, 存储密码key或者提供他们必要的值. 在这个使用方法中 .env 文件应该添加到 .gitignore 文件中而且永远不会被项目的合做者签入/签出. 这个方法确保里边没有敏感的 API Key 或者 密码在版本控制中出现从而减小了安全风险. 而且开发环境中的配置永远不会告知合做开发者.

添加配置到根目录下的 .env 文件, 确保 .env 文件添加到 .gitignore 从而不会签入到 CVS

S3_BUCKET=dotenv
SECRET_KEY=souper_seekret_key

如今建立一个 .env.example 文件, 而且签入到项目中. 这里配置和环境变量你须要设置的能够留空或者设置一些可有可无的数据. 这个方法告知人们这些数据是必须的, 可是不会提供真正环境中的数据.

S3_BUCKET=devbucket
SECRET_KEY=abc123

你可使用如下一行代码加载应用中的 .env 文件:

Dotenv::load(__DIR__);

全部定义的变量均可以经过 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');

嵌入变量

在一个变量中嵌入一个环境变量是能够的, 这样对于减小重复颇有用.

使用 {$…} 来包裹环境变量 e.g.

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

不可变

默认来讲, Dotenv 认为环境变量是不变的. 这就是说一旦设置就不能变动.

你能够用如下函数将环境变量设置为可变的

Dotenv::makeMutable();

… 一样你也可使用如下函数让其再也不可变

Dotenv::makeImmutable();

要求变量必须设置

使用 Dotenv, 你能够指定这个 ENV 变量必须设置, 如没有设置则会抛出异常. 这对于人们是很是有用的, 若是程序缺乏这个变量就不能运行.

使用如下语法:

Dotenv::required('DATABASE_DSN');

或者数组来定义:

Dotenv::required(array('DB_HOST', 'DB_NAME', 'DB_USER', 'DB_PASS'));

若是 ENV 变量缺乏, Dotenv 将抛出一个 RuntimeException :

Required environment variable missing or value not allowed: 'DB_USER', 'DB_PASS'

容许的值

你可能看到了上边的异常信息, 你能够设定一个可能范围值, 让你的环境变量遵照这个规则

Dotenv::required('SESSION_STORE', array('Filesystem', 'Memcached'));

一样的, 若是环境变量不在这个列表里, 你会收到一个类似的异常信息:

Required environment variable missing or value not allowed: 'SESSION_STORE'

注释

可使用 # 来注释字符. E.g.

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

使用注释

当一个开发者克隆你的代码库. 他们会收到一个额外的手册 一次性步骤 来手动的复制 .env.example 而且重命名为 .env 而且追加上他们本身的值(或者从其余开发者哪里获取到其余敏感值).

phpdotenv 被用来创建开发者环境可是不该该用在生产环境下. 在生产环境下, 须要设置真实的变量而没必要每次使用请求的时候都使用 .env 文件进行重载.

这个能够经过自动化部署工具来实现, 例如: Vagrant, chef, Puppet, 或者手动的经过云主机来实现, 例如: Pagodabox, Heroku.

贡献

1. Fork it

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. 建立新的拉取请求