Configuration

• Introduction
• 环境配置
  • 环境变量类型
  • 检索环境配置
  • 确定当前环境
  • 加密环境文件
• 访问配置值
• 配置缓存
• 调试模式
• 维护模式

#Introduction

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

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

应用概述

匆忙？您可以通过以下方式快速了解应用程序的配置、驱动程序和环境about 工匠命令：

php artisan about

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

php artisan about --only=environment

#环境配置

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

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

Laravel 的默认.env 文件包含一些常见的配置值，这些值可能会根据您的应用程序是在本地运行还是在生产 Web 服务器上运行而有所不同。这些值然后从各种 Laravel 配置文件中检索config 使用 Laravel 的目录env 功能。

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

Note
你的任何变量.env file 可以被外部环境变量覆盖，例如服务器级或系统级环境变量。

环境文件安全

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

但是，可以使用 Laravel 的内置加密你的环境文件环境加密.加密的环境文件可以安全地放置在源代码管理中。

额外的环境文件

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

#环境变量类型

你的所有变量.env 文件通常被解析为字符串，因此创建了一些保留值以允许您从env() 功能：

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

APP_NAME="My Application"

#检索环境配置

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

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

第二个值传递给env 功能是“默认值”。如果给定键不存在环境变量，则将返回此值。

#确定当前环境

当前的应用环境是通过APP_ENV 从你的变量.env 文件。您可以通过访问此值environment 上的方法App facade:

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

if (App::environment('local')) {
    // The environment is local
}

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

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

#加密环境文件

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

Encryption

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

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

php artisan env:encrypt --env=staging

Decryption

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

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

当。。。的时候env:decrypt 命令被调用，Laravel 将解密命令的内容.env.encrypted 文件并将解密的内容放在.env 文件。

这--cipher 选项可以提供给env:decrypt 命令以使用自定义加密密码：

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

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

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

#访问配置值

您可以使用全局轻松访问您的配置值config 在您的应用程序的任何地方运行。可以使用“点”语法访问配置值，其中包括您希望访问的文件名和选项。还可以指定默认值，如果配置选项不存在，将返回默认值：

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

// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');

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

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

#配置缓存

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

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

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

出于这个原因，您应该确保您只调用env 从您的应用程序配置中运行（config) 文件。通过检查 Laravel 的默认配置文件，您可以看到很多这样的例子。配置值可以从你的应用程序的任何地方使用config 功能如上所述.

Warning
如果你执行config:cache 命令在部署过程中，你应该确保你只调用env 从您的配置文件中运行。一旦配置被缓存，.env 文件不会被加载；因此，env 函数将只返回外部的、系统级的环境变量。

#调试模式

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

对于本地开发，您应该设置APP_DEBUG 环境变量到true.在您的生产环境中，此值应始终为false.如果变量设置为true 在生产中，您冒着将敏感配置值暴露给应用程序最终用户的风险。

#维护模式

当您的应用程序处于维护模式时，将为您的应用程序中的所有请求显示一个自定义视图。这使得在更新或执行维护时“禁用”您的应用程序变得容易。应用程序的默认中间件堆栈中包含维护模式检查。如果应用程序处于维护模式，则Symfony\Component\HttpKernel\Exception\HttpException 实例将被抛出，状态码为 503。

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

php artisan down

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

php artisan down --refresh=15

您还可以提供一个retry 的选项down 命令，这将被设置为Retry-After HTTP 标头的值，虽然浏览器通常会忽略此标头：

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 发送到您的浏览器，您将能够正常浏览该应用程序，就像它未处于维护模式一样。

Note
您的维护模式密码通常应由字母数字字符和可选的破折号组成。您应该避免在 URL 中使用具有特殊含义的字符，例如?.

预渲染维护模式视图

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

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

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

重定向维护模式请求

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

php artisan down --redirect=/

禁用维护模式

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

php artisan up

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

维护模式和队列

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

维护模式的替代方案

由于维护模式要求您的应用程序有几秒钟的停机时间，请考虑替代方案，例如Laravel 蒸气 和Envoyer 使用 Laravel 实现零停机部署。