[譯] 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. 建立新的拉取請求