后盾人

Appearance

配置 ​

介绍 ​

Laravel 框架的所有配置文件都存储在 config 目录中。每个选项都有文档记录，因此请随意浏览文件并熟悉可用的选项。

这些配置文件允许您配置数据库连接信息、邮件服务器信息以及各种其他核心配置值（如应用程序时区和加密密钥）。

about 命令 ​

Laravel 可以通过 about Artisan 命令显示应用程序的配置、驱动程序和环境的概述。

shell
php artisan about

如果您只对应用程序概述输出的特定部分感兴趣，则可以使用 --only 选项过滤该部分：

shell
php artisan about --only=environment

或者，要详细探索特定配置文件的值，您可以使用 config：show Artisan 命令：

shell
php artisan config:show database

环境配置 ​

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

为了简化这一点，Laravel 使用了 DotEnv PHP 库。在全新的 Laravel 安装中，应用程序的根目录将包含一个 .env.example 文件，该文件定义了许多常见的环境变量。在 Laravel 安装过程中，此文件将自动复制到 .env 中。

Laravel 的默认 .env 文件包含一些常见的配置值，这些值可能会因您的应用程序是在本地运行还是在生产 Web 服务器上运行而有所不同。然后，这些值由 config 目录中的配置文件使用 Laravel 的 env 函数读取。

如果您与团队一起开发，您可能希望继续在应用程序中包含和更新 .env.example 文件。通过将占位符值放在示例配置文件中，您团队中的其他开发人员可以清楚地看到运行应用程序需要哪些环境变量。

NOTE

.env 文件中的任何变量都可以被外部环境变量（如服务器级或系统级环境变量）覆盖。

环境文件安全 ​

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

但是，可以使用 Laravel 的内置环境加密来加密您的环境文件。加密的环境文件可以安全地置于源代码控制中。

其他环境文件 ​

在加载应用程序的环境变量之前，Laravel 会确定是否已从外部提供APP_ENV环境变量，或者是否指定了 --env CLI 参数。如果是这样，Laravel 将尝试加载一个 .env.[APP_ENV] 文件（如果存在）。如果不存在，则将加载默认的 .env 文件。

环境变量类型 ​

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

.env Valueenv() Value
true(bool) true
(true)(bool) true
false(bool) false
(false)(bool) false
empty(string) ''
(empty)(string) ''
null(null) null
(null)(null) null

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

ini
APP_NAME="My Application"

检索环境配置 ​

当您的应用程序收到请求时，.env 文件中列出的所有变量都将加载到 $_ENV PHP 超级全局变量中。但是，您可以使用 env 函数从配置文件中的这些变量中检索值。事实上，如果你查看 Laravel 配置文件，你会注意到许多选项已经在使用这个函数：

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

传递给 env 函数的第二个值是 “default value”。如果给定键不存在环境变量，则将返回此值。

确定当前环境 ​

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

php
    use Illuminate\Support\Facades\App;

    $environment = App::environment();

您还可以将参数传递给 environment 方法以确定环境是否与给定值匹配。如果环境与任何给定值匹配，该方法将返回 true：

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

    if (App::environment(['local', 'staging'])) {
        // The environment is either local OR staging...
    }

NOTE

可以通过定义服务器级 APP_ENV 环境变量来覆盖当前应用程序环境检测。

加密环境文件 ​

未加密的环境文件绝不应存储在源代码管理中。但是，Laravel 允许您加密环境文件，以便它们可以安全地与应用程序的其余部分一起添加到源代码控制中。

加密 ​

要加密环境文件，您可以使用 env：encrypt 命令：

shell
php artisan env:encrypt

运行 env：encrypt 命令将加密您的 .env 文件，并将加密的内容放在 .env.encrypted 文件中。解密密钥显示在命令的输出中，应存储在安全的密码管理器中。如果您想提供自己的加密密钥，您可以在调用命令时使用 --key 选项：

shell
php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

NOTE

提供的密钥长度应与所使用的加密密码所需的密钥长度匹配。默认情况下，Laravel 将使用 AES-256-CBC 密码，该密码需要 32 个字符的密钥。您可以在调用命令时通过传递 --cipher 选项，自由使用 Laravel 加密器支持的任何密码。

如果您的应用程序有多个环境文件，例如 .env 和 .env.staging，您可以通过 --env 选项提供环境名称来指定应加密的环境文件：

shell
php artisan env:encrypt --env=staging

解密 ​

要解密环境文件，您可以使用 env：decrypt 命令。此命令需要一个解密密钥，Laravel 将从 LARAVEL_ENV_ENCRYPTION_KEY 环境变量中检索该密钥：

shell
php artisan env:decrypt

或者，可以通过 --key 选项直接将密钥提供给命令：

shell
php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

调用 env：decrypt 命令时，Laravel 将解密 .env.encrypted 文件的内容，并将解密后的内容放入 .env 文件中。

可以为 env：decrypt 命令提供 --cipher 选项，以便使用自定义加密密码

shell
php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

如果您的应用程序有多个环境文件，例如 .env 和 .env.staging，您可以通过 --env 选项提供环境名称来指定应该解密的环境文件：

shell
php artisan env:decrypt --env=staging

为了覆盖现有的环境文件，您可以为 env：decrypt 命令提供 --force 选项：

shell
php artisan env:decrypt --force

访问配置值 ​

您可以使用 Config Facade或全局配置函数从应用程序中的任何位置轻松访问您的配置值。可以使用 “点” 语法访问配置值，其中包括要访问的文件名称和选项。还可以指定默认值，如果 configuration 选项不存在，将返回默认值：

php
    use Illuminate\Support\Facades\Config;

    $value = Config::get('app.timezone');

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

    // 如果配置值不存在，则检索默认值...
    $value = config('app.timezone', 'Asia/Seoul');

要在运行时设置配置值，你可以调用 Config Facade的 set 方法或将数组传递给 config 函数：

php
    Config::set('app.timezone', 'America/Chicago');

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

为了帮助进行静态分析，Config Facade还提供了类型化的配置检索方法。如果检索到的配置值与预期类型不匹配，将引发异常：

php
    Config::string('config-key');
    Config::integer('config-key');
    Config::float('config-key');
    Config::boolean('config-key');
    Config::array('config-key');

配置缓存 ​

为了提高应用程序的速度，您应该使用 config：cache Artisan 命令将所有配置文件缓存到一个文件中。这会将应用程序的所有配置选项合并到一个文件中，该文件可以由框架快速加载。

通常，您应该在生产部署过程中运行 php artisan config：cache 命令。在本地开发期间不应运行该命令，因为在应用程序开发过程中需要经常更改配置选项。

缓存配置后，框架在请求或 Artisan 命令期间不会加载应用程序的 .env 文件;因此，env 函数将仅返回外部系统级环境变量。

因此，您应该确保仅从应用程序的配置 （config） 文件中调用 env 函数。通过检查 Laravel 的默认配置文件，你可以看到很多例子。可以使用上述 config 函数从应用程序中的任何位置访问 configuration 值。

config：clear 命令可用于清除缓存的配置：

shell
php artisan config:clear

WARNING

如果您在部署过程中执行 config：cache 命令，则应确保仅从配置文件中调用 env 函数。缓存配置后，将不会加载 .env 文件;因此，env 函数将仅返回外部系统级环境变量。

配置发布 ​

Laravel 的大部分配置文件已经发布在应用程序的 config 目录中;但是，默认情况下不会发布某些配置文件（如 cors.php 和 view.php），因为大多数应用程序永远不需要修改它们。

但是，你可以使用 config：publish Artisan 命令来发布任何默认未发布的配置文件：

shell
php artisan config:publish

php artisan config:publish --all

调试模式 ​

config/app.php 配置文件中的 debug 选项决定了实际向用户显示多少有关错误的信息。默认情况下，此选项设置为遵循 APP_DEBUG 环境变量的值，该变量存储在 .env 文件中。

WARNING

对于本地开发，您应该将 APP_DEBUG 环境变量设置为 true。在您的生产环境中，此值应始终为 false。如果该变量在生产中设置为 true，则可能会向应用程序的最终用户公开敏感的配置值。

维护模式 ​

当应用程序处于维护模式时，将为应用程序中的所有请求显示自定义视图。这样，您就可以在应用程序更新或执行维护时轻松 “禁用” 应用程序。维护模式检查包含在应用程序的默认中间件堆栈中。如果应用程序处于维护模式，将引发状态代码为 503 Symfony\Component\HttpKernel\Exception\HttpException 的实例。

要启用维护模式，请执行 down Artisan 命令：

shell
php artisan down

如果您希望刷新 HTTP 标头与所有维护模式响应一起发送，则可以在调用 down 命令时提供刷新选项。Refresh 标头将指示浏览器在指定的秒数后自动刷新页面：

shell
php artisan down --refresh=15

您还可以为 down 命令提供重试选项，该选项将设置为 Retry-After HTTP 标头的值，尽管浏览器通常会忽略此标头：

shell
php artisan down --retry=60

绕过维护模式 ​

要允许使用 secret 令牌绕过维护模式，您可以使用 secret 选项指定维护模式绕过令牌：

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

将应用程序置于维护模式后，您可以导航到与此令牌匹配的应用程序 URL，Laravel 将向您的浏览器发出维护模式绕过 cookie：

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

如果您希望 Laravel 为您生成 secret 令牌，您可以使用 with-secret 选项。一旦应用程序处于维护模式，将向您显示 Secret：

shell
php artisan down --with-secret

访问此隐藏路由时，您将被重定向到应用程序的 / 路由。将 cookie 发送到您的浏览器后，您将能够正常浏览应用程序，就像它未处于维护模式一样。

NOTE

您的维护模式密钥通常应由字母数字字符和破折号（可选）组成。应避免在 URL 中使用具有特殊含义的字符，例如 ？ 或 &。

多个服务器上的维护模式 ​

默认情况下，Laravel 使用基于文件的系统确定您的应用程序是否处于维护模式。这意味着要激活维护模式，必须在托管应用程序的每个服务器上执行 php artisan down 命令。

或者，Laravel 提供了一种基于缓存的方法来处理维护模式。此方法只需要在一台服务器上运行 php artisan down 命令。要使用这种方法，请修改应用程序的 config/app.php 文件中的 “driver” 设置以进行缓存。然后，选择所有服务器都可以访问的缓存存储。这可确保在每个服务器上一致地维护维护模式状态：

php
'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

预渲染 Maintenance Mode 视图 ​

如果您在部署期间使用 php artisan down 命令，则当用户在 Composer 依赖项或其他基础设施组件更新时访问应用程序时，可能仍会偶尔遇到错误。发生这种情况是因为 Laravel 框架的很大一部分必须启动才能确定您的应用程序处于维护模式并使用模板引擎呈现维护模式视图。

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

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

重定向维护模式请求 ​

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

shell
php artisan down --redirect=/

禁用维护模式 ​

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

shell
php artisan up

NOTE

您可以通过在 中 resources/views/errors/503.blade.php 定义自己的模板来自定义默认维护模式模板。

维护模式和队列 ​

当您的应用程序处于维护模式时，不会处理任何排队的作业。一旦应用程序退出维护模式，作业将继续正常处理。

维护模式的替代方案 ​

由于维护模式要求您的应用程序有几秒钟的停机时间，因此请考虑使用 Laravel Vapor 和 Envoye 等替代方案，以使用 Laravel 实现零停机时间部署。

后盾人版权所有 © 2018-2024 创作不易请尊重他人劳动成果，未经授权禁止转载！