配置信息
这是一篇协同翻译的文章,你可以点击『我来翻译』按钮来参与翻译。
配置
介绍
Laravel框架的所有配置文件都存储在 config
目录中。每个选项都有文档说明,因此您可以随意查看这些文件,并熟悉可用的选项。
这些配置文件允许您配置数据库连接信息、邮件服务器信息以及各种其他核心配置值,例如应用程序时区和加密密钥。
about
命令
Laravel可以通过 about
Artisan命令显示应用程序配置、驱动程序和环境的概览。
php artisan about
如果您只对应用程序概览输出的特定部分感兴趣,您可以使用 --only
选项进行筛选:
php artisan about --only=environment
或者,要详细查看特定配置文件的值,您可以使用 config:show
Artisan命令:
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 Value |
env() Value |
---|---|
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
facade 的 environment
函数获取:
use Illuminate\Support\Facades\App;
$environment = App::environment();
你还可以将参数传递给 environment
函数,以确定环境是否与给定值匹配。如果环境与任何给定值匹配,则该方法将返回 true
if (App::environment('local')) {
// 本地环境
}
if (App::environment(['local', 'staging'])) {
// 本地或临时环境...
}
[!NOTE]
当前应用程序的环境检测,可以通过定义服务器级APP_ENV
环境变量来覆盖。
加密环境文件
未加密的环境文件不应存储在源代码控制中。然而,Laravel 允许你加密你的环境文件,以便它们可以安全地添加到源代码控制中。
加密
为了加密环境文件,你可以使用 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
选项即可
If your application has multiple environment files, such as .env
and .env.staging
, you may specify the environment file that should be encrypted by providing the environment name via the --env
option:
php artisan env:encrypt --env=staging
Decryption
To decrypt an environment file, you may use the env:decrypt
command. This command requires a decryption key, which Laravel will retrieve from the LARAVEL_ENV_ENCRYPTION_KEY
environment variable:
php artisan env:decrypt
Or, the key may be provided directly to the command via the --key
option:
php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
When the env:decrypt
command is invoked, Laravel will decrypt the contents of the .env.encrypted
file and place the decrypted contents in the .env
file.
The --cipher
option may be provided to the env:decrypt
command in order to use a custom encryption cipher:
php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC
If your application has multiple environment files, such as .env
and .env.staging
, you may specify the environment file that should be decrypted by providing the environment name via the --env
option:
php artisan env:decrypt --env=staging
In order to overwrite an existing environment file, you may provide the --force
option to the env:decrypt
command:
php artisan env:decrypt --force
Accessing Configuration Values
You may easily access your configuration values using the Config
facade or global config
function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you wish to access. A default value may also be specified and will be returned if the configuration option does not exist:
use Illuminate\Support\Facades\Config;
$value = Config::get('app.timezone');
$value = config('app.timezone');
// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');
有 1 个译文正在审阅中...
To set configuration values at runtime, you may invoke the Config
facade's set
method or pass an array to the config
function:
Config::set('app.timezone', 'America/Chicago');
config(['app.timezone' => 'America/Chicago']);
To assist with static analysis, the Config
facade also provides typed configuration retrieval methods. If the retrieved configuration value does not match the expected type, an exception will be thrown:
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Configuration Caching
To give your application a speed boost, you should cache all of your configuration files into a single file using the config:cache
Artisan command. This will combine all of the configuration options for your application into a single file which can be quickly loaded by the framework.
You should typically run the php artisan config:cache
command as part of your production deployment process. The command should not be run during local development as configuration options will frequently need to be changed during the course of your application's development.
Once the configuration has been cached, your application's .env
file will not be loaded by the framework during requests or Artisan commands; therefore, the env
function will only return external, system level environment variables.
For this reason, you should ensure you are only calling the env
function from within your application's configuration (config
) files. You can see many examples of this by examining Laravel's default configuration files. Configuration values may be accessed from anywhere in your application using the config
function described above.
有 1 个译文正在审阅中...
The config:clear
command may be used to purge the cached configuration:
php artisan config:clear
[!WARNING]
If you execute theconfig:cache
command during your deployment process, you should be sure that you are only calling theenv
function from within your configuration files. Once the configuration has been cached, the.env
file will not be loaded; therefore, theenv
function will only return external, system level environment variables.
Configuration Publishing
Most of Laravel's configuration files are already published in your application's config
directory; however, certain configuration files like cors.php
and view.php
are not published by default, as most applications will never need to modify them.
However, you may use the config:publish
Artisan command to publish any configuration files that are not published by default:
php artisan config:publish
php artisan config:publish --all
Debug Mode
The debug
option in your config/app.php
configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG
environment variable, which is stored in your .env
file.
[!WARNING]
For local development, you should set theAPP_DEBUG
environment variable totrue
. In your production environment, this value should always befalse
. If the variable is set totrue
in production, you risk exposing sensitive configuration values to your application's end users.
Maintenance Mode
When your application is in maintenance mode, a custom view will be displayed for all requests into your application. This makes it easy to "disable" your application while it is updating or when you are performing maintenance. A maintenance mode check is included in the default middleware stack for your application. If the application is in maintenance mode, a Symfony\Component\HttpKernel\Exception\HttpException
instance will be thrown with a status code of 503.
有 1 个译文正在审阅中...
To enable maintenance mode, execute the down
Artisan command:
php artisan down
If you would like the Refresh
HTTP header to be sent with all maintenance mode responses, you may provide the refresh
option when invoking the down
command. The Refresh
header will instruct the browser to automatically refresh the page after the specified number of seconds:
php artisan down --refresh=15
You may also provide a retry
option to the down
command, which will be set as the Retry-After
HTTP header's value, although browsers generally ignore this header:
php artisan down --retry=60
Bypassing Maintenance Mode
To allow maintenance mode to be bypassed using a secret token, you may use the secret
option to specify a maintenance mode bypass token:
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
After placing the application in maintenance mode, you may navigate to the application URL matching this token and Laravel will issue a maintenance mode bypass cookie to your browser:
https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515
If you would like Laravel to generate the secret token for you, you may use the with-secret
option. The secret will be displayed to you once the application is in maintenance mode:
php artisan down --with-secret
When accessing this hidden route, you will then be redirected to the /
route of the application. Once the cookie has been issued to your browser, you will be able to browse the application normally as if it was not in maintenance mode.
[!NOTE]
Your maintenance mode secret should typically consist of alpha-numeric characters and, optionally, dashes. You should avoid using characters that have special meaning in URLs such as?
or&
.
有 1 个译文正在审阅中...
Maintenance Mode on Multiple Servers
By default, Laravel determines if your application is in maintenance mode using a file-based system. This means to activate maintenance mode, the php artisan down
command has to be executed on each server hosting your application.
Alternatively, Laravel offers a cache-based method for handling maintenance mode. This method requires running the php artisan down
command on just one server. To use this approach, modify the maintenance mode variables in your application's .env
file. You should select a cache store
that is accessible by all of your servers. This ensures the maintenance mode status is consistently maintained across every server:
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database
Pre-Rendering the Maintenance Mode View
If you utilize the php artisan down
command during deployment, your users may still occasionally encounter errors if they access the application while your Composer dependencies or other infrastructure components are updating. This occurs because a significant part of the Laravel framework must boot in order to determine your application is in maintenance mode and render the maintenance mode view using the templating engine.
For this reason, Laravel allows you to pre-render a maintenance mode view that will be returned at the very beginning of the request cycle. This view is rendered before any of your application's dependencies have loaded. You may pre-render a template of your choice using the down
command's render
option:
php artisan down --render="errors::503"
Redirecting Maintenance Mode Requests
有 1 个译文正在审阅中...
While in maintenance mode, Laravel will display the maintenance mode view for all application URLs the user attempts to access. If you wish, you may instruct Laravel to redirect all requests to a specific URL. This may be accomplished using the redirect
option. For example, you may wish to redirect all requests to the /
URI:
php artisan down --redirect=/
Disabling Maintenance Mode
To disable maintenance mode, use the up
command:
php artisan up
[!NOTE]
You may customize the default maintenance mode template by defining your own template atresources/views/errors/503.blade.php
.
Maintenance Mode and Queues
While your application is in maintenance mode, no queued jobs will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode.
Alternatives to Maintenance Mode
Since maintenance mode requires your application to have several seconds of downtime, consider running your applications on a fully-managed platform like Laravel Cloud to accomplish zero-downtime deployment with Laravel.
有 1 个译文正在审阅中...
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
推荐文章: