Configuration

• 介绍
• 环境配置
  • 环境变量类型
  • 检索环境配置
  • 确定当前环境
  • 在调试页面隐藏环境变量
• 访问配置值
• 配置缓存
• 维护模式

介绍

Laravel 框架的所有配置文件都保存在 config 目录中。每个选项都有说明，你可随时查看这些文件并熟悉都有哪些配置选项可供你使用。

环境配置

对于应用程序运行的环境来说，不同的环境有不同的配置通常是很有用的。 例如，你可能希望在本地使用的缓存驱动不同于生产服务器所使用的缓存驱动。

Laravel 利用 Vance Lucas 的 PHP 库 DotEnv 使得此项功能的实现变得非常简单。在新安装好的 Laravel 应用程序中，其根目录会包含一个 .env.example 文件。如果是通过 Composer 安装的 Laravel，该文件会自动更名为 .env。否则，需要你手动更改一下文件名。

你的 .env 文件不应该提交到应用程序的源代码控制系统中，因为每个使用你的应用程序的开发人员 / 服务器可能需要有一个不同的环境配置。此外，在入侵者获得你的源代码控制仓库的访问权的情况下，这会成为一个安全隐患，因为任何敏感的凭据都被暴露了。

如果是团队开发，则可能希望应用程序中仍包含 .env.example 文件。因为通过在示例配置文件中放置占位值，团队中的其他开发人员可以清楚地看到哪些环境变量是运行应用程序所必需的。你也可以创建一个 .env.testing 文件，当运行 PHPUnit 测试或以 --env=testing 为选项执行 Artisan 命令时，该文件将覆盖 .env 文件中的值。

技巧：.env 文件中的所有变量都可被外部环境变量（比如服务器级或系统级环境变量）所覆盖。

环境变量类型

因为 .env 文件里所有的变量值都会被解析成字符串类型, 所以可以使用 env() 函数，函数里创建了一些保留值，可提供更大范围的变量类型：

如果你需要使用包含空格的值来定义环境变量，可以通过将值括在双引号中来实现。

APP_NAME="My Application"

检索环境配置

当你的应用程序收到请求时，此文件中列出的所有变量都将被加载到 PHP $_ENV 超全局变量中。 但是，你可以使用 env 的 helper 方法从配置文件中的这些变量中检索值。 实际上，如果您查看 Laravel 配置文件，您会注意到很多配置中已经使用了 helper 方法：

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

传递给 env 函数的第二个值是“默认值”。 如果给定的环境参数找不到对应的值，或不存在，则将使用此“默认值”。

确定当前环境

当前的应用程序环境是通过 .env 文件中的 APP_ENV 变量值确定的。你可以通过 App facade 的 environment 方法访问此值：

$environment = App::environment();

你也可以将参数传递给 environment 方法，以检查环境是否匹配给定值，如果环境匹配任何给定值，则该方法将返回 true：

if (App::environment('local')) {
    // 本地环境
}

if (App::environment(['local', 'staging'])) {
    // 本地环境或临时环境...
}

技巧：服务器级别的 APP_ENV 环境变量可以覆盖当前的应用程序环境检测。当你需要为不同的环境配置共享同一应用程序时，这很有用，因此你可以设置给定的主机以匹配服务器配置中的给定环境。

在调试页面隐藏环境变量

当一个异常未被捕获并且 APP_DEBUG 环境变量为 true 时，调试页面会显示所有的环境变量和内容。在某些情况下你可能想隐藏某些变量。你可以通过设置 config/app.php 配置文件中的 debug_hide 选项来完成这个操作。

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

return [

    // ...

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

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

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

访问配置值

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

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

要在运行时设置配置值，传递一个数组给 config 函数：

config(['app.timezone' => 'America/Chicago']);

配置缓存

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

通常来说，你应该把运行 php artisan config:cache（配置缓存）命令作为生产环境部署工作常态的一部分。而另一方面，由于在应用程序开发过程中经常需要修改配置选项，故该命令不应在本地开发环境下执行。

注意：如果在部署过程中执行 config:cache 命令，那么你应该确保只从配置文件内部调用 env 函数。一旦配置被缓存，.env 文件将不再被加载，所有对 env 函数的调用都将返回 null。

维护模式

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

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

php artisan down

你还可以向 down 命令提供 retry 选项。该选项 retry 值可用于设置 HTTP 请求头中 Retry-After 的值：

php artisan down --retry=60

绕过维护模式

即使在维护模式下，你也可以使用 secret 选项指定维护模式的绕过令牌：

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

将应用程序置于维护模式后，您可以访问与该令牌匹配的应用程序 URL，Laravel 将向您的浏览器发出一个维护模式绕过 cookie：

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

当访问这个隐藏的路由时，您将被重定向到应用程序的 / 路由。一旦 cookie 被发布到您的浏览器，您将能够正常浏览应用程序，就好像它没有处于维护模式一样。

预渲染维护模式视图

如果在部署环境中使用 php artisan down 命令，当你的 Composer 依懒或其基础组件更新的时候，你的用户可能遇到偶然性的错误。这是因为 Laravel 框架的重要部分必须启动才能确定应用程序处于维护模式，并使用模板引擎呈现维护模式视图。

因此，Laravel 允许您预先呈现一个维护模式视图，该视图将在请求周期的最开始返回。此视图在加载应用程序的任何依赖项之前呈现。可以使用 down 命令的 render 选项预渲染所选模板：

php artisan down --render="errors::503"

重定向维护模式请求

在维护模式下，Laravel 将显示用户尝试访问的所有应用程序 url 的维护模式视图。如果您愿意，您可以指示 Laravel 将所有请求重定向到特定的 URL。这可以使用 redirect 选项来完成。例如，您可能希望将所有请求重定向到 / URI：

php artisan down --redirect=/

关闭维护模式

要关闭维护模式，请使用 up 命令：

php artisan up

技巧：你可以通过修改 resources/views/errors/503.blade.php 模板文件来自定义默认维护模式模板。

维护模式 & 队列

当应用程序处于维护模式时，不会处理 队列任务。而这些任务会在应用程序退出维护模式后再继续处理。

维护模式的替代方案

维护模式会导致应用程序有数秒的停机（不响应）时间，因此你可以考虑使用像 Envoyer 这样的替代方案，以便与 Laravel 完成零停机时间部署。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。