設定

• イントロダクション
• 環境設定
  • 環境変数の型
  • 環境設定の取得
  • 現在の環境の判別
  • 環境ファイルの暗号化
• 設定値へのアクセス
• 設定のキャッシュ
• 設定の公開
• デバッグモード
• メンテナンスモード

イントロダクション

Laravelフレームワークのすべての設定ファイルはconfigディレクトリに保存されています。各オプションにはドキュメントが付いているので、ファイルを自由に見て、利用可能なオプションに慣れてください。

これらの設定ファイルを使用すると、データベース接続情報、メールサーバー情報、およびアプリケーションのURLや暗号化キーなどのさまざまなコア設定値を設定できます。

aboutコマンド

Laravelは、Artisanコマンドaboutを使用して、アプリケーションの設定、ドライバ、環境の概要を表示できます。

1php artisan about

アプリケーション概要出力の特定のセクションにのみ関心がある場合は、--onlyオプションを使用してそのセクションをフィルタリングできます。

1php artisan about --only=environment

または、特定の設定ファイル値を詳細に調べるには、Artisanコマンドconfig:showを使用します。

1php artisan config:show database

環境設定

アプリケーションが実行されている環境に基づいて、異なる設定値を持つと便利なことがよくあります。たとえば、ローカルでは本番サーバとは異なるキャッシュドライバを使用したい場合などです。

これを簡単にするために、LaravelはDotEnv PHPライブラリを利用しています。Laravelを新規インストールすると、アプリケーションのルートディレクトリに、多くの一般的な環境変数を定義する.env.exampleファイルが含まれています。Laravelのインストールプロセス中に、このファイルは自動的に.envにコピーされます。

Laravelのデフォルト.envファイルには、アプリケーションがローカルで実行されているか、本番Webサーバで実行されているかによって異なる可能性のある、一般的な設定値がいくつか含まれています。これらの値は、Laravelのenv関数を使用して、configディレクトリ内の設定ファイルによって読み取られます。

チームで開発している場合は、.env.exampleファイルを引き続きアプリケーションに含めて更新したいことでしょう。サンプル設定ファイルにプレースホルダー値を設定することで、チームの他の開発者は、アプリケーションを実行するためにどの環境変数が必要かを明確に確認できます。

環境ファイルのセキュリティ

.envファイルは、アプリケーションのソース管理にコミットしないでください。アプリケーションを使用する開発者/サーバーごとに、異なる環境設定が必要になる可能性があるためです。さらに、侵入者がソース管理リポジトリにアクセスした場合、機密性の高い認証情報が公開されてしまうため、セキュリティ上のリスクとなります。

しかし、Laravelの組み込み環境暗号化を使用して環境ファイルを暗号化することができます。暗号化された環境ファイルは、ソース管理に安全に配置できます。

追加の環境ファイル

アプリケーションの環境変数をロードする前に、LaravelはAPP_ENV環境変数が外部から提供されているか、または--env CLI引数が指定されているかを判断します。もしそうであれば、Laravelは.env.[APP_ENV]ファイルが存在すれば、それをロードしようとします。存在しない場合は、デフォルトの.envファイルがロードされます。

環境変数の型

.envファイル内のすべての変数は通常、文字列として解析されるため、env()関数からより広い範囲の型を返せるように、いくつかの予約値が作成されています。

スペースを含む値を持つ環境変数を定義する必要がある場合は、値を二重引用符で囲むことで定義できます。

1APP_NAME="My Application"

環境設定の取得

.envファイルにリストされているすべての変数は、アプリケーションがリクエストを受信したときにPHPのスーパーグローバル$_ENVにロードされます。ただし、env関数を使用して、設定ファイルでこれらの変数の値を取得できます。実際、Laravelの設定ファイルを確認すると、多くのオプションがすでにこの関数を使用していることがわかります。

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

env関数に渡される２番目の値は「デフォルト値」です。この値は、指定されたキーの環境変数が存在しない場合に返されます。

現在の環境の判別

現在のアプリケーション環境は、.envファイルのAPP_ENV変数を介して決定されます。この値には、App ファサードのenvironmentメソッドを介してアクセスできます。

1use Illuminate\Support\Facades\App;
2 
3$environment = App::environment();

environmentメソッドに引数を渡して、環境が特定の値と一致するかどうかを判断することもできます。このメソッドは、環境が指定された値のいずれかと一致する場合にtrueを返します。

1if (App::environment('local')) {
2    // The environment is local
3}
4 
5if (App::environment(['local', 'staging'])) {
6    // The environment is either local OR staging...
7}

環境ファイルの暗号化

暗号化されていない環境ファイルは、ソース管理に保存しないでください。しかし、Laravelでは環境ファイルを暗号化できるため、アプリケーションの他の部分と一緒に安全にソース管理へ追加できます。

暗号化

環境ファイルを暗号化するには、env:encryptコマンドを使用します。

1php artisan env:encrypt

env:encryptコマンドを実行すると、.envファイルが暗号化され、暗号化されたコンテンツが.env.encryptedファイルに配置されます。復号キーはコマンドの出力に表示されるため、安全なパスワードマネージャーに保存してください。独自の暗号化キーを指定したい場合は、コマンドを呼び出すときに--keyオプションを使用できます。

1php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

アプリケーションに.envや.env.stagingなど、複数の環境ファイルがある場合は、--envオプションで環境名を指定することにより、暗号化する環境ファイルを指定できます。

1php artisan env:encrypt --env=staging

復号

環境ファイルを復号するには、env:decryptコマンドを使用します。このコマンドには復号キーが必要であり、LaravelはLARAVEL_ENV_ENCRYPTION_KEY環境変数からそれを取得します。

1php artisan env:decrypt

または、--keyオプションを使用して、キーをコマンドに直接指定することもできます。

1php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

env:decryptコマンドが呼び出されると、Laravelは.env.encryptedファイルの内容を復号し、復号した内容を.envファイルに配置します。

カスタム暗号化方式を使用するために、env:decryptコマンドに--cipherオプションを指定できます。

1php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

アプリケーションに.envや.env.stagingなど、複数の環境ファイルがある場合は、--envオプションで環境名を指定することにより、復号する環境ファイルを指定できます。

1php artisan env:decrypt --env=staging

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

1php artisan env:decrypt --force

設定値へのアクセス

アプリケーションのどこからでも、Configファサードまたはグローバルconfig関数を使用して、設定値に簡単にアクセスできます。設定値には、アクセスしたいファイルとオプションの名前を含む「ドット」記法を使用してアクセスできます。デフォルト値も指定でき、設定オプションが存在しない場合に返されます。

1use Illuminate\Support\Facades\Config;
2 
3$value = Config::get('app.timezone');
4 
5$value = config('app.timezone');
6 
7// Retrieve a default value if the configuration value does not exist...
8$value = config('app.timezone', 'Asia/Seoul');

実行時に設定値を設定するには、Configファサードのsetメソッドを呼び出すか、config関数に配列を渡します。

1Config::set('app.timezone', 'America/Chicago');
2 
3config(['app.timezone' => 'America/Chicago']);

静的解析を支援するために、Configファサードは型付けされた設定取得メソッドも提供しています。取得した設定値が期待される型と一致しない場合、例外が投げられます。

1Config::string('config-key');
2Config::integer('config-key');
3Config::float('config-key');
4Config::boolean('config-key');
5Config::array('config-key');

設定のキャッシュ

アプリケーションを高速化するには、config:cache Artisanコマンドを使用して、すべての設定ファイルを１つのファイルにキャッシュする必要があります。これにより、アプリケーションのすべての設定オプションが１つのファイルに結合され、フレームワークによって迅速にロードできるようになります。

通常、本番環境へのデプロイプロセスの一環としてphp artisan config:cacheコマンドを実行する必要があります。ローカル開発中にこのコマンドを実行しないでください。アプリケーションの開発過程で設定オプションを頻繁に変更する必要があるためです。

設定がキャッシュされると、リクエストやArtisanコマンドの実行時にアプリケーションの.envファイルはフレームワークによってロードされなくなります。したがって、env関数は外部のシステムレベルの環境変数のみを返します。

このため、アプリケーションの設定（config）ファイル内からのみenv関数を呼び出すようにしてください。Laravelのデフォルト設定ファイルを調べると、この多くの例を確認できます。設定値には、前述のconfig関数を使用して、アプリケーションのどこからでもアクセスできます。

config:clearコマンドを使用して、キャッシュされた設定をパージ（削除）できます。

1php artisan config:clear

設定の公開

Laravelのほとんどの設定ファイルは、アプリケーションのconfigディレクトリにすでに公開されています。ただし、cors.phpやview.phpなどの特定の設定ファイルは、ほとんどのアプリケーションで変更する必要がないため、デフォルトでは公開されません。

しかし、config:publish Artisanコマンドを使用して、デフォルトで公開されていない設定ファイルを公開できます。

1php artisan config:publish
2 
3php artisan config:publish --all

デバッグモード

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

メンテナンスモード

アプリケーションがメンテナンスモードのときは、アプリケーションへのすべてのリクエストに対してカスタムビューが表示されます。これにより、更新中やメンテナンス実行中にアプリケーションを簡単に「無効化」できます。メンテナンスモードのチェックは、アプリケーションのデフォルトのミドルウェアスタックに含まれています。アプリケーションがメンテナンスモードの場合、ステータスコード503のSymfony\Component\HttpKernel\Exception\HttpExceptionインスタンスが投げられます。

メンテナンスモードを有効にするには、down Artisanコマンドを実行します。

1php artisan down

すべてのメンテナンスモードのレスポンスでRefresh HTTPヘッダーを送信したい場合は、downコマンドを呼び出すときにrefreshオプションを指定できます。Refreshヘッダーは、指定された秒数の後にページを自動的に更新するようにブラウザに指示します。

1php artisan down --refresh=15

downコマンドにretryオプションを指定することもできます。これはRetry-After HTTPヘッダーの値として設定されますが、ブラウザは通常このヘッダーを無視します。

1php artisan down --retry=60

メンテナンスモードのバイパス

秘密のトークンを使用してメンテナンスモードをバイパスできるようにするには、secretオプションを使用してメンテナンスモードのバイパストークンを指定します。

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

アプリケーションをメンテナンスモードにした後、このトークンに一致するアプリケーションURLにアクセスすると、Laravelはブラウザにメンテナンスモードのバイパスクッキーを発行します。

1https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Laravelに秘密のトークンを生成させたい場合は、with-secretオプションを使用できます。アプリケーションがメンテナンスモードになると、秘密のトークンが表示されます。

1php artisan down --with-secret

この隠しルートにアクセスすると、アプリケーションの/ルートにリダイレクトされます。クッキーがブラウザに発行されると、メンテナンスモードでないかのように通常通りアプリケーションを閲覧できるようになります。

複数サーバーでのメンテナンスモード

デフォルトでは、Laravelはファイルベースのシステムを使用してアプリケーションがメンテナンスモードにあるかどうかを判断します。これは、メンテナンスモードを有効にするには、アプリケーションをホストしている各サーバーでphp artisan downコマンドを実行する必要があることを意味します。

あるいは、Laravelはメンテナンスモードを処理するためのキャッシュベースの方法を提供しています。この方法では、１つのサーバーでphp artisan downコマンドを実行するだけで済みます。このアプローチを使用するには、アプリケーションのconfig/app.phpファイルの「driver」設定をcacheに変更します。次に、すべてのサーバーからアクセス可能なキャッシュstoreを選択します。これにより、メンテナンスモードのステータスがすべてのサーバーで一貫して維持されるようになります。

1'maintenance' => [
2    'driver' => 'cache',
3    'store' => 'database',
4],

メンテナンスモードビューの事前レンダリング

デプロイ中にphp artisan downコマンドを利用する場合でも、Composerの依存関係やその他のインフラストラクチャコンポーネントが更新されている間にユーザーがアプリケーションにアクセスすると、エラーが発生することがあります。これは、アプリケーションがメンテナンスモードにあることを判断し、テンプレートエンジンを使用してメンテナンスモードビューをレンダリングするために、Laravelフレームワークの大部分を起動する必要があるためです。

このため、Laravelではリクエストサイクルの最初に返されるメンテナンスモードビューを事前にレンダリングできます。このビューは、アプリケーションの依存関係がロードされる前にレンダリングされます。downコマンドのrenderオプションを使用して、選択したテンプレートを事前にレンダリングできます。

1php artisan down --render="errors::503"

メンテナンスモードリクエストのリダイレクト

メンテナンスモード中、LaravelはユーザーがアクセスしようとするすべてのアプリケーションURLに対してメンテナンスモードビューを表示します。必要に応じて、すべてのリクエストを特定のURLにリダイレクトするようにLaravelに指示できます。これはredirectオプションを使用して実現できます。たとえば、すべてのリクエストを/ URIにリダイレクトしたい場合があります。

1php artisan down --redirect=/

メンテナンスモードの無効化

メンテナンスモードを無効にするには、upコマンドを使用します。

1php artisan up

メンテナンスモードとキュー

アプリケーションがメンテナンスモードの間、キュー投入されたジョブは処理されません。アプリケーションがメンテナンスモードを解除されると、ジョブは通常通り処理され続けます。

メンテナンスモードの代替案

メンテナンスモードではアプリケーションに数秒のダウンタイムが必要になるため、Laravel Cloudのようなフルマネージドプラットフォームでアプリケーションを実行し、Laravelでゼロダウンタイムデプロイを実現することを検討してください。