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

アプリケーションの概要Application Overview

お急ぎですか？about Artisanコマンドで、アプリケーションの設定、ドライバ、環境の概要を簡単に確認できます。In a hurry? You can get a quick overview of your application's configuration, drivers, and environment via the about Artisan command:

php artisan about

アプリケーション概要の出力のうち、特定のセクションのみ興味がある場合は、--onlyオプションを使用してそのセクションをフィルタリングすることができます。If you're only interested in a particular section of the application overview output, you may filter for that section using the --only option:

php artisan about --only=environment

環境設定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 Note:.envファイルにあるすべての変数は、サーバレベルやシステムレベルで定義されている、外部の環境変数によってオーバーライドすることができます。Note
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.

しかしながら、Laravelの組み込みの環境の暗号化を使用して、環境ファイルを暗号化することも可能です。暗号化した環境ファイルは、安全にソース管理下に置けます。However, it is possible to encrypt your environment file using Laravel's built-in environment encryption[#encrypting-environment-files]. Encrypted environment files may be placed in source control safely.

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

アプリケーションの環境変数を読み込む前に、LaravelはAPP_ENV環境変数が外部から提供されているか、もしくは--env CLI引数が指定されているかを判断します。その場合、Laravelは.env.[APP_ENV]ファイルが存在すれば、それを読み込もうとします。存在しない場合は、デフォルトの.envファイルを読み込みます。Before loading your application's environment variables, Laravel determines if an 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ファイルでリストされているすべての変数は、アプリケーションがリクエストを受信すると、$_ENV PHPスーパーグローバルへロードされます。ただし、env関数を使用して、設定ファイル内のこれらの変数から値を取得することができます。実際、Laravel設定ファイルを確認すると、多くのオプションがすでにこの関数を使用していることがわかります。All of the variables listed in the .env file will be loaded into the $_ENV PHP super-global when your application receives a request. However, you may use the env function 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 function:

'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 Note:現在のアプリケーション環境の検出は、サーバレベルのAPP_ENV環境変数を定義することで上書きできます。Note
The current application environment detection can be overridden by defining a server-level APP_ENV environment variable.

環境ファイルの暗号化Encrypting Environment Files

暗号化してない環境ファイルは、絶対にソースコントロールで保存してはいけません。しかし、Laravelでは環境ファイルを暗号化でき、アプリケーションの他の部分と一緒にソースコントロールへ安全に追加できます。Unencrypted environment files should never be stored in source control. However, Laravel allows you to encrypt your environment files so that they may safely be added to source control with the rest of your application.

暗号化Encryption

環境ファイルを暗号化するには、env:encryptコマンドを使用します。To encrypt an environment file, you may use the env:encrypt command:

php artisan env:encrypt

env:encryptコマンドを実行すると、.envファイルが暗号化され、暗号化した内容を.env.encryptedファイルへ格納します。復号化キーはコマンドの出力として表示されますので、安全なパスワードマネージャで保存しておく必要があります。もし、自分自身で暗号化キーを指定する場合はコマンド実行時に、--keyオプションを使用してください。Running the env:encrypt command will encrypt your .env file and place the encrypted contents in an .env.encrypted file. The decryption key is presented in the output of the command and should be stored in a secure password manager. If you would like to provide your own encryption key you may use the --key option when invoking the command:

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

lightbulb Note:指定するキーの長さは、使用する暗号化方式で要求される鍵の長さと合わせる必要があります。デフォルトでLaravelは、３２文字のキーを必要とするAES-256-CBC暗号を使用します。コマンド起動時に、--cipherオプションを指定すれば、Laravelの 暗号化でサポートする暗号を自由に指定できます。Note
The length of the key provided should match the key length required by the encryption cipher being used. By default, Laravel will use the AES-256-CBC cipher which requires a 32 character key. You are free to use any cipher supported by Laravel's encrypter[/docs/{{version}}/encryption] by passing the --cipher option when invoking the command.

アプリケーションで.envや.env.stagingなど、複数の環境ファイルを使用している場合は、--envオプションで環境名を指定することで、暗号化する環境ファイルを指定します。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

環境ファイルを復号化するには、env:decryptコマンドを使用します。このコマンドは復号化キーを必要とし、LaravelはLARAVEL_ENV_ENCRYPTION_KEY環境変数からこれを取得します。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

もしくは、--keyオプションで、キーを直接コマンドへ指定することもできます。Or, the key may be provided directly to the command via the --key option:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

env:decryptコマンドを実行すると、Laravelは.env.encryptedファイルの内容を復号化し、復号化した内容を.envファイルへ格納します。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.

env:decryptコマンドへ、--cipherオプションを指定すると、カスタム暗号を使用できます。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

アプリケーションが.envや.env.stagingなど、複数の環境ファイルを使用している場合は、--envオプションで環境名を指定することにより、復号化する環境ファイルを指定できます。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

既存の環境ファイルを上書きするには、env:decryptコマンドへ--forceオプションを指定します。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

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

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

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

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

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.

warning Warning! 開発過程の一環としてconfig:cacheコマンド実行を採用する場合は、必ずenv関数を設定ファイルの中だけで使用してください。設定ファイルがキャッシュされると、.envファイルはロードされません。したがって、env関数は外部システムレベルの環境変数のみを返すだけです。Warning
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オプションを使い、メンテナンスモードパイパストークンを指定します。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"

アプリケーションをメンテナンスモードにしたあとで、このトークンと同じ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 Note:メンテナンスモードのシークレットは、通常、英数字とオプションでダッシュで構成されるべきです。URLの中で特別な意味を持つ文字、例えば ? の使用は避けるべきです。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 ?.

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 Note:resources/views/errors/503.blade.phpを独自に定義することにより、メンテナンスモードのデフォルトテンプレートをカスタマイズできます。Note
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.