配置

Laravel 中文文档 / 入门指南

配置

简介

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

环境配置

基于应用运行的环境使用不同的配置值通常是很有用的。例如,可能希望在本地服务器上使用与生产服务器不同的缓存驱动。

Laravel 利用 Vance Lucas 的 PHP 库 DotEnv 让此功能可以很容易实现。新安装的 Laravel 应用根目录包含一个 .env.example 文件。如果是使用 Composer 安装的 Laravel,该文件会自动改名为 .env。否则,您需要自己更改一下文件名。

.env 文件不应提交到应用的代码版本控制中,因为每个使用应用的开发者/服务器可能需要不同的环境配置。此外,当黑客获得代码仓库访问权时,这也会成为一个安全隐患,因为所有敏感数据都泄露了。

团队开发中,可能还希望应用中包含 .env.example 文件。可以将占位值放在示例配置文件中,这样团队的其他开发者就可以清楚地看到运行应用所需的环境变量。同样可以创建一个 .env.testing 文件,当运行 PHPUnit 测试或执行 Artisan 命令并添加 --env=testing 选项时,此文件中的值将覆盖 .env 文件中的。

.env 文件中的任何变量都会被外部环境变量(例如服务器或系统环境变量)覆盖。

环境变量类型

.env 文件里的所有变量都被解析为字符串,因此创建了一些保留值允许您从 env() 函数返回更多变量类型:

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

如果定义的环境变量的值含有空格,应将其放在双引号中:

APP_NAME="My Application"

获取环境配置

当应用收到请求时,.env 文件中列出的所有变量将被加载到 PHP 的超全局变量 $ _ENV 中。可以使用 env 函数来获取这些变量的值。实际上,如果查看 Laravel 的配置文件,就会注意到有些选项已经使用了该函数:

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

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

确定当前环境

当前应用环境通过 .env 文件里的 APP_ENV 变量决定。可以使用 App Facadeenvironment 方法来获取该值:

$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' => 'America/Chicago']);

缓存配置

为了提升应用速度,应该使用 Artisan 命令 config:cache 将所有配置文件缓存到单个文件中。合并所有配置项到单个文件后,该文件会被框架快速加载。

通常应该把运行 php artisan config:cache 命令作为生产环境部署的一部分。该命令不应在本地开发环境下运行,因为配置项在应用开发过程中经常需要更改。

如果部署过程中执行 config:cache 命令,应该确保只在配置文件里调用 env 函数。配置缓存后,不会加载 .env 文件,并且所有 env 函数调用都会返回 null

维护模式

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

启用维护模式,可以执行 Artisan 命令 down

php artisan down

也可以为 down 命令添加 --message--retry 选项。--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 这样的替代方案,让 Laravel 完成零停机时间部署。

  上一篇 下一篇  

作者:ilaoniu

牛哥,俗称哞哞。单纯的九零后理工小青年。喜欢折腾,爱玩,爱安卓,爱音乐,爱游戏,爱电影,爱旅游...