[ Laravel 5.8 中文文档 ] 入门——配置信息

>>> 文档总目录 <<<

介绍

Laravel框架的所有配置文件都存储在config目录中。每个选项都有注释说明，因此您可以随时查看文件并熟悉可用的选项。

环境配置

根据运行应用程序的环境提供不同的配置值通常很有帮助。例如，可能在本地使用的缓存驱动，和在生产服务器上使用的不同。

为了使这个变得简单，Laravel使用了Vance Lucas 的DotEnv PHP库。在新安装的Laravel中，应用程序的根目录下包含一个 .env.example 文件。如果您通过 Composer 安装的 Laravel，则此文件将自动重命名为 .env。否则，您应该手动重命名该文件。

您的.env文件不应该提交给应用程序的代码控制系统中，因为使用您的应用程序的每个开发人员/服务器都可能需要不同的环境配置。此外，如果入侵者获得对源代码控制存储库的访问权限，这将是一种安全风险，因为任何敏感凭证都会暴露出来。

如果你是在一个团队中进行开发，则需要将 .env.example 文件随你的应用代码一起提交到源码控制中：将一些配置值以占位符的方式放置在 .env.example 文件中，这样其他开发者就会很清楚运行你的应用需要配置哪些环境变量。

你也可以创建一个 .env.testing 文件，当运行 PHPUnit 测试或以--env=testing 为选项执行 Artisan 命令时，该文件将覆盖 .env 文件中的值。

.env 文件中的所有变量都可以被外部环境变量覆盖，例如服务器级别或系统级别的环境变量。

环境变量类型

.env 文件中所有变量都会被解析为字符串，因此创建了一些保留值以便从 env() 函数返回更广泛的类型：

如果你需要定义一个包含空格的环境变量值，可以通过将字符串放到双引号中来实现：

APP_NAME="My Application"

检索环境配置

应用每次接受请求时，.env 中列出的所有配置及其对应值都会被载入到 PHP 超全局变量 $_ENV 中，然后你就可以在应用中通过辅助函数 env 来获取这些配置值。实际上，如果你去查看 Laravel 的配置文件，就会发现很多地方已经在使用这个辅助函数了：

'debug' => env('APP_DEBUG', false),

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

确定当前环境

当前应用环境由 .env 文件中的 APP_ENV 变量决定，你可以通过 App 门面上的 environment 方法来访问其值：

$environment = App::environment();

你还可以传递参数给 environment 方法，以检查当前的环境配置是否与给定值匹配。 如果与给定值匹配，该方法将返回 true：

if (App::environment('local')) {
    // 当前环境是 local
}

if (App::environment(['local', 'staging'])) {
    // 当前的环境是 local 或 staging...
}

注：当前应用环境判断可以被服务器级别环境变量 APP_ENV 覆盖。当你需要在不同环境配置间共享同一应用时很有用，你可以在服务器配置中设置一个给定主机来匹配给定环境。

在调试页面隐藏环境变量

如果异常没有捕获到而 APP_DEBUG 环境变量又被设置成了 true，调试页面将会显示所有的环境变量及其内容。在某些案例中，你可能想要隐藏特定的变量，这可以通过更新配置文件config/app.php 中的 debug_blacklist 选项来实现。

环境变量、服务器或者请求数据中都有一些变量是可用的。因此，你可能需要将 $_ENV 和 $_SERVER 的变量加入到黑名单中：

return [

    // ...

    'debug_blacklist' => [
        '_ENV' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_SERVER' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_POST' => [
            'password',
        ],
    ],
];

访问配置值

你可以轻松地在应用程序的任何位置使用全局 config 函数来访问配置值。配置值的访问可以使用「点」语法，这其中包含了要访问的文件和选项的名称。还可以指定默认值，如果配置选项不存在，则返回默认值：

$value = config('app.timezone');

如果要在运行时设置配置值，传递数组参数到 config 方法即可：

config(['app.timezone' => 'Asia/Shanghai']);

配置缓存

为了给你的应用程序提升速度，你应该使用 Artisan 命令 config:cache 将所有的配置文件缓存到单个文件中。这会把你的应用程序中所有的配置选项合并成一个单一的文件，然后框架会快速加载这个文件。

通常来说，你应该把运行 php artisan config:cache 命令作为生产环境部署常规工作的一部分。这个命令不应在本地开发环境下运行，因为配置选项在应用程序开发过程中是经常需要被更改的。

注：如果在部署过程中执行 config:cache 命令，需要确保只在配置文件中调用了 env 方法。一旦配置文件被缓存后，.env 文件将不能被加载，所有对 env 函数的调用都会返回 null。

维护模式

当应用程序处于维护模式时，所有对应用程序的请求都显示为一个自定义视图。这样可以在更新或执行维护时轻松地「关闭」你的应用程序。 维护模式检查包含在应用程序的默认中间件栈中。如果应用程序处于维护模式，则将抛出一个状态码为 503 的 MaintenanceModeException 异常。

要启用维护模式，只需执行下面的 Artisan 的 down 命令：

php artisan down

还可以提供 message 和retry 选项给 down 命令。message 的值用于显示或记录自定义消息，而 retry 的值用于设置 HTTP 请求头的 Retry-After：

php artisan down --message="Upgrading Database" --retry=60

即使在维护模式下，也可以使用命令allow选项置顶特定的IP地址或网络：

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

要禁用维护模式，请使用以下up命令：

php artisan up

注：你可以通过定义自己的模板来定制默认的维护模式模板，自定义模板视图位于 resources/views/errors/503.blade.php。

维护模式 & 队列

当您的应用程序处于维护模式时，不会处理队列任务。当应用退出维护模式这些任务才会被继续正常处理。

维护模式的替代方案

由于维护模式命令的执行需要几秒时间，你可以考虑使用 Envoyer 实现零秒下线作为替代方案。

>>> 文档总目录 <<<