Laravel源码解析之ENV配置

Laravel在启动时会加载项目中的 .env文件。对于应用程序运行的环境来说&＃xff0c;不同的环境有不同的配置通常是很有用的。 例如&＃xff0c;你可能希望在本地使用测试的 Mysql数据库而在上线后希望项目能够自动切换到生产 Mysql数据库。本文将会详细介绍 env 文件的使用与源码的分析。

Env文件的使用

多环境env的设置

项目中 env文件的数量往往是跟项目的环境数量相同&＃xff0c;假如一个项目有开发、测试、生产三套环境那么在项目中应该有三个 .env.dev、 .env.test、 .env.prod三个环境配置文件与环境相对应。三个文件中的配置项应该完全一样&＃xff0c;而具体配置的值应该根据每个环境的需要来设置。

接下来就是让项目能够根据环境加载不同的 env文件了。具体有三种方法&＃xff0c;可以按照使用习惯来选择使用:

• 在环境的 nginx配置文件里设置 APP_ENV环境变量 fastcgi_param APP_ENV dev;

• 设置服务器上运行PHP的用户的环境变量&＃xff0c;比如在 www用户的 /home/www/.bashrc中添加 exportAPP_ENV dev

• 在部署项目的持续集成任务或者部署脚本里执行 cp.env.dev.env

针对前两种方法&＃xff0c; Laravel会根据 env(&＃39;APP_ENV&＃39;)加载到的变量值去加载对应的文件 .env.dev、 .env.test这些。 具体在后面源码里会说&＃xff0c;第三种比较好理解就是在部署项目时将环境的配置文件覆盖到 .env文件里这样就不需要在环境的系统和 nginx里做额外的设置了。

自定义env文件的路径与文件名

env文件默认放在项目的根目录中&＃xff0c; laravel 为用户提供了自定义 ENV 文件路径或文件名的函数&＃xff0c;

例如&＃xff0c;若想要自定义 env 路径&＃xff0c;可以在 bootstrap 文件夹中 app.php 中使用 Application实例的 useEnvironmentPath方法&＃xff1a;

$app &＃61; new Illuminate\Foundation\Application(realpath(__DIR__.&＃39;/../&＃39;)
);
$app->useEnvironmentPath(&＃39;/customer/path&＃39;)


若想要自定义 env 文件名称&＃xff0c;就可以在 bootstrap 文件夹中 app.php 中使用 Application实例的 loadEnvironmentFrom方法&＃xff1a;

$app &＃61; new Illuminate\Foundation\Application(realpath(__DIR__.&＃39;/../&＃39;)
);
$app->loadEnvironmentFrom(&＃39;customer.env&＃39;)


Laravel 加载ENV配置

Laravel加载 ENV的是在框架处理请求之前&＃xff0c;bootstrap过程中的 LoadEnvironmentVariables阶段中完成的。

我们来看一下 \Illuminate\Foundation\Bootstrap\LoadEnvironmentVariables的源码来分析下 Laravel是怎么加载 env中的配置的。

namespace Illuminate\Foundation\Bootstrap;
use Dotenv\Dotenv;
use Dotenv\Exception\InvalidPathException;
use Symfony\Component\Console\Input\ArgvInput;
use Illuminate\Contracts\Foundation\Application;
class LoadEnvironmentVariables
{/*** Bootstrap the given application.** &＃64;param  \Illuminate\Contracts\Foundation\Application  $app* &＃64;return void*/public function bootstrap(Application $app){if ($app->configurationIsCached()) {return;}$this->checkForSpecificEnvironmentFile($app);try {(new Dotenv($app->environmentPath(), $app->environmentFile()))->load();} catch (InvalidPathException $e) {//}}/*** Detect if a custom environment file matching the APP_ENV exists.** &＃64;param  \Illuminate\Contracts\Foundation\Application  $app* &＃64;return void*/protected function checkForSpecificEnvironmentFile($app){if ($app->runningInConsole() && ($input &＃61; new ArgvInput)->hasParameterOption(&＃39;--env&＃39;)) {if ($this->setEnvironmentFilePath($app, $app->environmentFile().&＃39;.&＃39;.$input->getParameterOption(&＃39;--env&＃39;))) {return;}}if (! env(&＃39;APP_ENV&＃39;)) {return;}$this->setEnvironmentFilePath($app, $app->environmentFile().&＃39;.&＃39;.env(&＃39;APP_ENV&＃39;));}/*** Load a custom environment file.** &＃64;param  \Illuminate\Contracts\Foundation\Application  $app* &＃64;param  string  $file* &＃64;return bool*/protected function setEnvironmentFilePath($app, $file){if (file_exists($app->environmentPath().&＃39;/&＃39;.$file)) {$app->loadEnvironmentFrom($file);return true;}return false;}
}


在他的启动方法 bootstrap中&＃xff0c; Laravel会检查配置是否缓存过以及判断应该应用那个 env文件&＃xff0c;针对上面说的根据环境加载配置文件的三种方法中的头两种&＃xff0c;因为系统或者nginx环境变量中设置了 APP_ENV&＃xff0c;所以Laravel会在 checkForSpecificEnvironmentFile方法里根据 APP_ENV的值设置正确的配置文件的具体路径&＃xff0c; 比如 .env.dev或者 .env.test&＃xff0c;而针对第三中情况则是默认的 .env&＃xff0c; 具体可以参看下面的 checkForSpecificEnvironmentFile还有相关的Application里的两个方法的源码&＃xff1a;

protected function checkForSpecificEnvironmentFile($app)
{if ($app->runningInConsole() && ($input &＃61; new ArgvInput)->hasParameterOption(&＃39;--env&＃39;)) {if ($this->setEnvironmentFilePath($app, $app->environmentFile().&＃39;.&＃39;.$input->getParameterOption(&＃39;--env&＃39;))) {return;}}if (! env(&＃39;APP_ENV&＃39;)) {return;}$this->setEnvironmentFilePath($app, $app->environmentFile().&＃39;.&＃39;.env(&＃39;APP_ENV&＃39;));
}
namespace Illuminate\Foundation;
class Application ....
{public function environmentPath(){return $this->environmentPath ?: $this->basePath;}public function environmentFile(){return $this->environmentFile ?: &＃39;.env&＃39;;}
}


判断好后要读取的配置文件的路径后&＃xff0c;接下来就是加载 env里的配置了。

(new Dotenv($app->environmentPath(), $app->environmentFile()))->load();


Laravel使用的是 Dotenv的PHP版本 vlucas/phpdotenv

class Dotenv
{public function __construct($path, $file &＃61; &＃39;.env&＃39;){$this->filePath &＃61; $this->getFilePath($path, $file);$this->loader &＃61; new Loader($this->filePath, true);}public function load(){return $this->loadData();}protected function loadData($overload &＃61; false){$this->loader &＃61; new Loader($this->filePath, !$overload);return $this->loader->load();}
}


它依赖 /Dotenv/Loader来加载数据&＃xff1a;

class Loader
{public function load(){$this->ensureFileIsReadable();$filePath &＃61; $this->filePath;$lines &＃61; $this->readLinesFromFile($filePath);foreach ($lines as $line) {if (!$this->isComment($line) && $this->looksLikeSetter($line)) {$this->setEnvironmentVariable($line);}}return $lines;}
}


Loader读取配置时 readLinesFromFile函数会用 file函数将配置从文件中一行行地读取到数组中去&＃xff0c;然后排除以 #开头的注释&＃xff0c;针对内容中包含 &＃61;的行去调用 setEnvironmentVariable方法去把文件行中的环境变量配置到项目中去&＃xff1a;

namespace Dotenv;
class Loader
{public function setEnvironmentVariable($name, $value &＃61; null){list($name, $value) &＃61; $this->normaliseEnvironmentVariable($name, $value);$this->variableNames[] &＃61; $name;// Don&＃39;t overwrite existing environment variables if we&＃39;re immutable// Ruby&＃39;s dotenv does this with &＃96;ENV[key] ||&＃61; value&＃96;.if ($this->immutable && $this->getEnvironmentVariable($name) !&＃61;&＃61; null) {return;}// If PHP is running as an Apache module and an existing// Apache environment variable exists, overwrite itif (function_exists(&＃39;apache_getenv&＃39;) && function_exists(&＃39;apache_setenv&＃39;) && apache_getenv($name)) {apache_setenv($name, $value);}if (function_exists(&＃39;putenv&＃39;)) {putenv("$name&＃61;$value");}$_ENV[$name] &＃61; $value;$_SERVER[$name] &＃61; $value;}public function getEnvironmentVariable($name){switch (true) {case array_key_exists($name, $_ENV):return $_ENV[$name];case array_key_exists($name, $_SERVER):return $_SERVER[$name];default:$value &＃61; getenv($name);return $value &＃61;&＃61;&＃61; false ? null : $value; // switch getenv default to null}}
}


Dotenv实例化 Loader的时候把 Loader对象的 $immutable属性设置成了 false&＃xff0c; Loader设置变量的时候如果通过 getEnvironmentVariable方法读取到了变量值&＃xff0c;那么就会跳过该环境变量的设置。所以 Dotenv默认情况下不会覆盖已经存在的环境变量&＃xff0c;这个很关键&＃xff0c;比如说在 docker的容器编排文件里&＃xff0c;我们会给 PHP应用容器设置关于 Mysql容器的两个环境变量

   environment:- "DB_PORT&＃61;3306"- "DB_HOST&＃61;database"


这样在容器里设置好环境变量后&＃xff0c;即使 env文件里的 DB_HOST为 homestead用 env函数读取出来的也还是容器里之前设置的 DB_HOST环境变量的值 database(docker中容器链接默认使用服务名称&＃xff0c;在编排文件中我把mysql容器的服务名称设置成了database, 所以php容器要通过database这个host来连接mysql容器)。因为用我们在持续集成中做自动化测试的时候通常都是在容器里进行测试&＃xff0c;所以 Dotenv不会覆盖已存在环境变量这个行为就相当重要这样我就可以只设置容器里环境变量的值完成测试而不用更改项目里的 env文件&＃xff0c;等到测试完成后直接去将项目部署到环境上就可以了。

如果检查环境变量不存在那么接着Dotenv就会把环境变量通过PHP内建函数 putenv设置到环境中去&＃xff0c;同时也会存储到 $_ENV和 $_SERVER这两个全局变量中。

在项目中读取env配置

在Laravel应用程序中可以使用 env()函数去读取环境变量的值&＃xff0c;比如获取数据库的HOST&＃xff1a;

env(&＃39;DB_HOST&＃96;, &＃39;localhost&＃39;);


传递给 env 函数的第二个值是「默认值」。如果给定的键不存在环境变量&＃xff0c;则会使用该值。

我们来看看 env函数的源码&＃xff1a;

function env($key, $default &＃61; null)
{$value &＃61; getenv($key);if ($value &＃61;&＃61;&＃61; false) {return value($default);}switch (strtolower($value)) {case &＃39;true&＃39;:case &＃39;(true)&＃39;:return true;case &＃39;false&＃39;:case &＃39;(false)&＃39;:return false;case &＃39;empty&＃39;:case &＃39;(empty)&＃39;:return &＃39;&＃39;;case &＃39;null&＃39;:case &＃39;(null)&＃39;:return;}if (strlen($value) > 1 && Str::startsWith($value, &＃39;"&＃39;) && Str::endsWith($value, &＃39;"&＃39;)) {return substr($value, 1, -1);}return $value;
}


它直接通过 PHP内建函数 getenv读取环境变量。

我们看到了在加载配置和读取配置的时候&＃xff0c;使用了 putenv和 getenv两个函数。 putenv设置的环境变量只在请求期间存活&＃xff0c;请求结束后会恢复环境之前的设置。因为如果php.ini中的 variables_order配置项成了 GPCS不包含 E的话&＃xff0c;那么php程序中是无法通过 $_ENV读取环境变量的&＃xff0c;所以使用 putenv动态地设置环境变量让开发人员不用去关注服务器上的配置。而且在服务器上给运行用户配置的环境变量会共享给用户启动的所有进程&＃xff0c;这就不能很好的保护比如 DB_PASSWORD、 API_KEY这种私密的环境变量&＃xff0c;所以这种配置用 putenv设置能更好的保护这些配置信息&＃xff0c; getenv方法能获取到系统的环境变量和 putenv动态设置的环境变量。