Laravel 8.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.

これら設定ファイルを使用すると、データベース接続情報、メールサーバ情報、およびアプリケーションのタイムゾーンや暗号化キーなどの他のさまざまなコア設定値などを設定できます。These configuration files allow you to configure things like your database connection information, your mail server information, as well as various other core configuration values such as your application timezone and encryption key.

環境設定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はDotEnv PHPライブラリを利用しています。Laravelの新規インストールでは、アプリケーションのルートディレクトリに、多くの一般的な環境変数を定義する.env.exampleファイルが含まれます。Laravelのインストールプロセス中に、このファイルは自動的に.envへコピーされます。To make this a cinch, Laravel utilizes the DotEnv[https://github.com/vlucas/phpdotenv] PHP library. In a fresh Laravel installation, the root directory of your application will contain a .env.example file that defines many common environment variables. During the Laravel installation process, this file will automatically be copied to .env.

Laravelのデフォルトの.envファイルには、アプリケーションがローカルで実行されているか本番Webサーバで実行されているかにより異なる可能性のある、一般的な設定値が含まれています。これらの値は、Laravelのenv関数を使用してconfigディレクトリ内のさまざまなLaravel設定ファイルから取得されています。Laravel's default .env file contains some common configuration values that may differ based on whether your application is running locally or on a production web server. These values are then retrieved from various Laravel configuration files within the config directory using Laravel's env function.

チームで開発している場合は、アプリケーションに.env.exampleファイルを含め続けることをお勧めします。サンプル設定ファイルにプレースホルダー値を配置することにより、チームの他の開発者は、アプリケーションを実行するために必要な環境変数を明確に確認できます。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.

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 File Security

アプリケーションを使用する開発者/サーバごとに異なる環境設定が必要になる可能性があるため、.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.

追加の環境ファイルAdditional Environment Files

アプリケーションの環境変数を読み込む前に、LaravelはAPP_ENV環境変数が外部から提供されているか、もしくは--env CLI引数が指定されているかを判断します。その場合、Laravelは.env.[APP_ENV]ファイルが存在すれば、それを読み込もうとします。存在しない場合は、デフォルトの.envファイルを読み込みます。Before loading your application's environment variables, Laravel determines if either the APP_ENV environment variable has been externally provided or if the --env CLI argument has been specified. If so, Laravel will attempt to load an .env.[APP_ENV] file if it exists. If it does not exist, the default .env file will be loaded.

環境変数タイプEnvironment Variable Types

通常、.envファイル内のすべての変数は文字列として解析されるため、env()関数からより広範囲の型を返せるように、いくつかの予約値が作成されています。All variables in your .env files are typically 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 many of the options are 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 returned 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]:

use Illuminate\Support\Facades\App;

$environment = App::environment();

environmentメソッドに引数を渡して、環境が特定の値と一致するかどうかを判定することもできます。環境が指定された値のいずれかに一致する場合、メソッドはtrueを返します。You may also pass arguments to the environment method to determine 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 defining a server-level APP_ENV environment variable.

設定値へのアクセス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コマンドを使用してすべての設定ファイルを1つのファイルへキャッシュする必要があります。これにより、アプリケーションのすべての設定オプションが１ファイルに結合され、フレームワークによってすばやくロードされます。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.

通常、本番デプロイメントプロセスの一部としてphp artisan config:cacheコマンドを実行する必要があります。アプリケーションの開発中は設定オプションを頻繁に変更する必要があるため、ローカル開発中はコマンドを実行しないでください。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.

Note: note 開発過程の一環としてconfig:cacheコマンド実行を採用する場合は、必ずenv関数を設定ファイルの中だけで使用してください。設定ファイルがキャッシュされると、.envファイルはロードされません。したがって、env関数は外部システムレベルの環境変数のみを返すだけです。{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; therefore, the env function will only return external, system level environment variables.

デバッグモードDebug Mode

config/app.php設定ファイルのdebugオプションは、エラーに関する情報が実際にユーザーに表示される量を決定します。デフォルトでは、このオプションは、.envファイルに保存されているAPP_DEBUG環境変数の値を尊重するように設定されています。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.

ローカル開発の場合は、APP_DEBUG環境変数をtrueに設定する必要があります。実稼働環境では、この値は常にfalseである必要があります。本番環境で変数がtrueに設定されていると、機密性の高い設定値がアプリケーションのエンドユーザーに公開されるリスクがあります。For local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false. If the variable is set to true in production, you risk exposing sensitive configuration values to your application's end users.

メンテナンスモードMaintenance Mode

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

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

php artisan down

メンテナンスモードのすべてのレスポンスで、RefreshのHTTPヘッダを送信したい場合は、downコマンドを実行する際に、refreshオプションを指定します。Refreshヘッダは、指定した秒数後にページを自動的に更新するようブラウザに指示します。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

また、downコマンドにretryオプションを指定し、HTTPヘッダのRetry-After値を設定できますが、通常ブラウザはこのヘッダを無視します。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

メンテナンスモード状態でもsecretオプションを使い、メンテナンスモードパイパストークンを指定できます。Even while in maintenance mode, you may use the secret option to specify a maintenance mode bypass token:

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

アプリケーションをメンテナンスモードにしたあとで、このトークンと同じURLによりブラウザでアプリケーションにアクセスすると、メンテナンスモードバイパスクッキーがそのブラウザへ発行されます。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

この隠しルートへアクセスすると、次にアプリケーションの/ルートへリダイレクトされます。ブラウザへこのクッキーが一度発行されると、メンテナンスモードでない状態と同様に、アプリケーションへ普通にブラウズできます。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.

lightbulb">Tip!! メンテナンスモードのシークレットは、通常、英数字とオプションでダッシュで構成されるべきです。URLの中で特別な意味を持つ文字、例えば ? の使用は避けるべきです。{tip} 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 ?.

Viewメンテナンスモードビューの事前レンダリングPre-Rendering The Maintenance Mode View

開発時にphp artisan downコマンドを使うと、Composerの依存パッケージやその他の基盤コンポーネントのアップデート中に、アプリケーションへユーザーがアクセスすると、エラーが発生することがあります。この理由は、アプリケーションがメンテナンスモードであると判断することやテンプレートエンジンによりメンテナンスモードビューをレンダーするには、Laravelフレームワークのかなりの部分が起動している必要があるからです。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.

このため、Laravelはリクエストサイクルの最初に返されるメンテナンスモードビューを事前レンダーできます。このビューは、アプリケーションの依存関係が読み込まれる前にレンダーされます。downコマンドのrenderオプションで、選んだテンプレートを事前レンダーできます。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

URI:メンテナンスモード中、Laravelはユーザーがアクセスしてきたアプリケーションの全URLに対し、メンテナンスモードビューを表示します。お望みならば、全リクエストを特定のＵＲＬへリダイレクトすることも可能です。redirectオプションを使用してください。例として、全リクエストを/のＵＲＩへリダイレクトするとしましょう。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

メンテナンスモードから抜けるには、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を使う開発においてはダウンタイムゼロを達成するために、Laravel VaporやEnvoyerなどの代替手段を検討してください。Since maintenance mode requires your application to have several seconds of downtime, consider alternatives like Laravel Vapor[https://vapor.laravel.com] and Envoyer[https://envoyer.io] to accomplish zero-downtime deployment with Laravel.