Laravel 7.x 設定

イントロダクションIntroduction

Laravelフレームワークの全設定ファイルは、configディレクトリに保存されています。各オプションには詳しいコメントが付いているので、各ファイルを一読し、使用できるオプションを把握しておきましょう。All of the configuration files for the Laravel framework are stored in the config directory. Each option is documented, so feel free to look through the files and get familiar with the options available to you.

環境設定Environment Configuration

アプリケーションを実行している環境にもとづき、別の設定値に切り替えられると便利です。たとえば、ローカルと実働サーバでは、異なったキャッシュドライバを使いたいことでしょう。It is often helpful to have different configuration values based on the environment where the application is running. For example, you may wish to use a different cache driver locally than you do on your production server.

これを簡単にできるようにするため、LaravelではVance Lucas氏により作成された、DotEnv PHPライブラリーを使用しています。新たにLaravelをインストールすると、アプリケーションのルートディレクトリには、.env.exampleファイルが含まれています。ComposerによりLaravelをインストールした場合は自動的に、このファイルは.envにコピーされます。Composerを使わずにインストールした場合は、コピーしてください。To make this a cinch, Laravel utilizes the DotEnv[https://github.com/vlucas/phpdotenv] PHP library by Vance Lucas. In a fresh Laravel installation, the root directory of your application will contain a .env.example file. If you install Laravel via Composer, this file will automatically be copied to .env. Otherwise, you should copy the file manually.

.envファイルは、アプリケーションのソースコントロールに含めるべきでありません。各ユーザー／サーバは異なった環境設定が必要だからです。さらに、侵入者がソースコントロールリポジトリへアクセスすることが起きれば、機密性の高い情報が漏れてしまうセキュリティリスクになります。Your .env file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration. Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.

チーム開発を行っている場合、.env.exampleファイルをアプリケーションに含めたいと思うでしょう。サンプルの設定ファイルに、プレースホルダーとして値を設定しておけば、チームの他の開発者は、アプリケーションを実行するために必要な環境変数をはっきりと理解できるでしょう。さらに、.env.testingファイルを作成することもできます。このファイルは、PHPUnitテスト実行時やArtisanコマンドへ--env=testingオプションを指定した場合に、.envファイルをオーバーライドします。If you are developing with a team, you may wish to continue including a .env.example file with your application. By putting placeholder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application. You may also create a .env.testing file. This file will override the .env file when running PHPUnit tests or executing Artisan commands with the --env=testing option.

lightbulb">Tip!! .envファイルにあるすべての変数は、サーバレベルやシステムレベルで定義されている、外部の環境変数によってオーバーライドすることができます。{tip} Any variable in your .env file can be overridden by external environment variables such as server-level or system-level environment variables.

環境変数タイプEnvironment Variable Types

.envファイル中の全変数は、文字列としてパースされます。env()関数でさまざまなタイプを返すために、予約語があります。All variables in your .env files are parsed as strings, so some reserved values have been created to allow you to return a wider range of types from the env() function:

空白を含む値を環境変数に定義する場合は、ダブル引用符で囲ってください。If you need to define an environment variable with a value that contains spaces, you may do so by enclosing the value in double quotes.

APP_NAME="My Application"

環境設定の取得Retrieving Environment Configuration

このファイルにリストしている値は、アプリケーションがリクエストを受け取った時点で、$_ENV PHPスーパーグローバル変数へロードされます。しかし、設定ファイルの変数をenvヘルパを使用して、値を取得できます。実際にLaravelの設定ファイルを見てもらえば、このヘルパで多くのオプションが使われているのに気がつくでしょう。All of the variables listed in this file will be loaded into the $_ENV PHP super-global when your application receives a request. However, you may use the env helper to retrieve values from these variables in your configuration files. In fact, if you review the Laravel configuration files, you will notice several of the options already using this helper:

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

env関数の第２引数は「デフォルト値」です。この値は指定したキーの環境変数が存在しない場合に返されます。The second value passed to the env function is the "default value". This value will be used if no environment variable exists for the given key.

現在環境の決定Determining The Current Environment

現在のアプリケーション環境は、.envファイルのAPP_ENV変数により決まります。APPファサードのenvironmentメソッドにより、この値へアクセスできます。The current application environment is determined via the APP_ENV variable from your .env file. You may access this value via the environment method on the App facade[/docs/{{version}}/facades]:

$environment = App::environment();

指定した値と一致する環境であるかを確認するために、environmentメソッドへ引数を渡すこともできます。必要であれば、複数の値をenvironmentメソッドへ渡せます。値のどれかと一致すれば、メソッドはtrueを返します。You may also pass arguments to the environment method to check if the environment matches a given value. The method will return true if the environment matches any of the given values:

if (App::environment('local')) {
    // 環境はlocal
}

if (App::environment(['local', 'staging'])) {
    // 環境はlocalかstaging
}

lightbulb">Tip!! 現在のアプリケーション環境は、サーバレベルのAPP_ENV環境変数によりオーバーライドされます。これは同じアプリケーションを異なった環境で実行する場合に便利です。特定のホストに対し、サーバの設定で適切な環境を指定できます。{tip} The current application environment detection can be overridden by a server-level APP_ENV environment variable. This can be useful when you need to share the same application for different environment configurations, so you can set up a given host to match a given environment in your server's configurations.

デバッグページの環境変数非表示Hiding Environment Variables From Debug Pages

例外が補足されず、APP_DEBUG環境変数がtrueになっていると、すべての環境変数とその内容がデバッグページに表示されます。特定の変数は非表示にしたい場合があるでしょう。config/app.php設定ファイルのdebug_hideオプションを更新してください。When an exception is uncaught and the APP_DEBUG environment variable is true, the debug page will show all environment variables and their contents. In some cases you may want to obscure certain variables. You may do this by updating the debug_hide option in your config/app.php configuration file.

いくつかの変数は、環境変数とサーバ／リクエストデータの両方で利用できます。そのため、$_ENVと$_SERVER両方で隠す必要があります。Some variables are available in both the environment variables and the server / request data. Therefore, you may need to hide them for both $_ENV and $_SERVER:

return [

    // ...

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

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

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

設定値へのアクセスAccessing Configuration Values

アプリケーションのどこからでもグローバルのconfigヘルパ関数を使用し、設定値へ簡単にアクセスできます。設定値はファイルとオプションの名前を含む「ドット」記法を使いアクセスします。デフォルト値も指定でき、設定オプションが存在しない場合に、返されます。You may easily access your configuration values using the global config helper 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:

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

// 設定値が存在しない場合、デフォルト値を取得する
$value = config('app.timezone', 'Asia/Seoul');

実行時に設定値をセットするには、configヘルパへ配列で渡してください。To set configuration values at runtime, pass an array to the config helper:

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

設定キャッシュConfiguration Caching

アプリケーションをスピードアップさせるために、全設定ファイルを一つのファイルへまとめる、config:cache Artisanコマンドを使ってください。これによりアプリケーションの全設定ファイルのオプションが、単一のファイルに結合され、フレームワークが素早くロードできるようになります。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 will be loaded quickly by the framework.

一般的には、本番環境へのデプロイ作業の一環として、php artisan config:cacheコマンドを実行すべきでしょう。アプリケーションの開発期間中は設定が頻繁に変更されることも多いので、ローカルでの開発中にこのコマンドを実行してはいけません。You should typically run the php artisan config:cache command as part of your production deployment routine. 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.

Note: note 開発過程の一環としてconfig:cacheコマンド実行を採用する場合は、必ずenv関数を設定ファイルの中だけで使用してください。設定ファイルがキャッシュされると、.envファイルはロードされなくなり、env関数の呼び出しはすべてnullを返します。{note} If you execute the config:cache command during your deployment process, you should be sure that you are only calling the env function from within your configuration files. Once the configuration has been cached, the .env file will not be loaded and all calls to the env function will return null.

メンテナンスモードMaintenance Mode

アプリケーションをメンテナンスモードにすると、アプリケーションに対するリクエストに対し、すべてカスタムビューが表示されるようになります。アプリケーションのアップデート中や、メンテナンス中に、アプリケーションを簡単に「停止」状態にできます。メンテナンスモードのチェックは、アプリケーションのデフォルトミドルウェアスタックに含まれています。アプリケーションがメンテナンスモードの時、ステータスコード503でMaintenanceModeException例外が投げられます。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 MaintenanceModeException will be thrown with a status code of 503.

メンテナンスモードにするには、down Artisanコマンドを実行します。To enable maintenance mode, execute the down Artisan command:

php artisan down

downコマンドには、messageとretryオプションを付けることもできます。messageの値はカスタムメッセージを表示、もしくはログするために使用し、retryの値はHTTPヘッダのRetry-Afterとしてセットされます。You may also provide message and retry options to the down command. The message value may be used to display or log a custom message, while the retry value will be set as the Retry-After HTTP header's value:

php artisan down --message="Upgrading Database" --retry=60

コマンドのallowオプションを使用し、メンテナンスモードであっても、アプリケーションへアクセスを許すIPアドレスやネットワークを指定できます。Even while in maintenance mode, specific IP addresses or networks may be allowed to access the application using the command's allow option:

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

メンテナンスモードから抜けるには、upコマンドを使います。To disable maintenance mode, use the up command:

php artisan up

lightbulb">Tip!! resources/views/errors/503.blade.phpを独自に定義することにより、メンテナンスモードのデフォルトテンプレートをカスタマイズできます。{tip} You may customize the default maintenance mode template by defining your own template at resources/views/errors/503.blade.php.

メンテナンスモードとキューMaintenance Mode & Queues

アプリケーションがメンテナンスモードの間、キューされたジョブは実行されません。メンテナンスモードから抜け、アプリケーションが通常状態へ戻った時点で、ジョブは続けて処理されます。While your application is in maintenance mode, no queued jobs[/docs/{{version}}/queues] will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode.

メンテナンスモードの代替Alternatives To Maintenance Mode

メンテナンスモードでは、アプリケーションがその間ダウンタイムになってしまいますので、Laravelでの開発でゼロダウンタイムを実現するEnvoyerのような代替サービスを検討してください。Since maintenance mode requires your application to have several seconds of downtime, consider alternatives like Envoyer[https://envoyer.io] to accomplish zero-downtime deployment with Laravel.