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

aboutコマンドThe about Command

Laravelでは、about Artisanコマンドでアプリケーションの設定、ドライバ、環境の概要を表示できます。Laravel can display an 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

特定の設定ファイルの値を詳しく調べるには、config:show Artisanコマンドを使います。Or, to explore a specific configuration file's values in detail, you may use the config:show Artisan command:

php artisan config:show database

環境設定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'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 read by the configuration files within the config directory using Laravel's env function.

チームで開発を行っているのであれば、.env.exampleファイルをアプリケーションに含めて更新し続けることをお勧めします。example設定ファイルにプレースホルダの値を入れることで、チームの他の開発者はアプリケーションの実行に必要な環境変数を明確に知ることができます。If you are developing with a team, you may wish to continue including and updating the .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ファサードとconfigグローバル関数を使い、簡単に設定値にアクセスできます。設定値には「ドット」構文を使いアクセスでき、アクセスしたいファイル名とオプション名を指定します。デフォルト値を指定することもでき、その設定オプションが存在しない場合に返します。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');

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

実行時に設定値をセットするには、Configファサードのsetメソッドを呼び出すか、config 関数に配列を渡します。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']);

静的解析を支援するため、Configファサードは型付き設定値の取得メソッドも提供しています。取得した設定値が期待した型と一致しない場合、例外を投げます。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

アプリケーションの速度を上げるには、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.

いったん設定がキャッシュされると、リクエスト時やArtisanコマンド実行時に、アプリケーションの.envファイルをフレームワークは読み込みません。したがって、env関数は外部のシステムレベルの環境変数のみを返します。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.

この理由により、アプリケーションの設定ファイル（config）の中からしか、env関数を呼び出さないようにする必要があります。Laravelのデフォルトの設定ファイルを調べると、多くの例を確認できます。設定値には、アプリケーションのどこからでも、上記のconfig関数を使用してアクセスできます。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[#accessing-configuration-values].

config:clearコマンドは、キャッシュされた設定を消去するために使用します。The config:clear command may be used to purge the cached configuration:

php artisan config:clear

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.

設定のリソース公開Configuration Publishing

Laravelのほとんどの設定ファイルは、あらかじめアプリケーションのconfigディレクトリでリソース公開されていますが、cors.phpやview.phpのような特定の設定ファイルは、ほとんどのアプリケーションでは変更する必要がないため、デフォルトでは公開していません。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.

しかし、config:publish Artisanコマンドを使用し、デフォルトで公開していない設定ファイルをリソース公開できます。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

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.

warning Warning! ローカル開発の場合は、APP_DEBUG環境変数をtrueに設定する必要があります。実稼働環境では、この値は常にfalseである必要があります。本番環境で変数がtrueに設定されていると、機密性の高い設定値がアプリケーションのエンドユーザーに公開されるリスクがあります。[!WARNING]
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

Laravelにシークレットトークンを生成してもらいたい場合は、with-secretオプションを使用します。アプリケーションがメンテナンスモードになると、シークレットが表示されます。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.

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 ? or &.

複数サーバでのメンテナンスモードMaintenance Mode on Multiple Servers

Laravelはデフォルトで、ファイルベースのシステムを使ってアプリケーションがメンテナンスモードかを判断します。つまり、メンテナンスモードを有効にするには、アプリケーションをホストしている各サーバ上でphp artisan downコマンドを実行する必要があります。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.

別の方法としてLaravelは、メンテナンスモードをキャッシュベースで処理する方法も提供しています。この方法では、１つのサーバ上でphp artisan downコマンドを実行する必要があるだけです。この方法を使用するには、アプリケーションのconfig/app.phpファイルの"driver"設定をcacheに変更してください。そして、すべてのサーバからアクセス可能なキャッシュstoreを選択してください。これにより、メンテナンスモードの状態がすべてのサーバで一貫して維持されるようになります。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 "driver" setting in the config/app.php file of your application to cache. Then, select a cache store that is accessible by all your servers. This ensures the maintenance mode status is consistently maintained across every server:

'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

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 and 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.