設定 10.x Laravel

イントロダクション

Laravelフレームワークの全設定ファイルは、configディレクトリに保存されています。各オプションには詳しいコメントが付いているので、各ファイルを一読し、使用できるオプションを把握しておきましょう。

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

アプリケーションの概要

お急ぎですか？about Artisanコマンドで、アプリケーションの設定、ドライバ、環境の概要を簡単に確認できます。

php artisan about

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

php artisan about --only=environment

環境設定

アプリケーションを実行している環境にもとづき、別の設定値に切り替えられると便利です。たとえば、ローカルと実働サーバでは、異なったキャッシュドライバを使いたいことでしょう。

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

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

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

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

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

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

しかしながら、Laravelの組み込みの環境の暗号化を使用して、環境ファイルを暗号化することも可能です。暗号化した環境ファイルは、安全にソース管理下に置けます。

追加の環境ファイル

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

環境変数タイプ

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

`.env`値	`env()`値
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ''
(empty)	(string) ''
null	(null) null
(null)	(null) null

スペースを含む値で環境変数を定義する必要がある場合は、値をダブルクォーテーションで囲むことによって定義できます。

APP_NAME="My Application"

環境設定の取得

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

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

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

現在環境の決定

現在のアプリケーション環境は、.envファイルのAPP_ENV変数により決まります。APPファサードのenvironmentメソッドにより、この値へアクセスできます。

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

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

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

Note: 現在のアプリケーション環境の検出は、サーバレベルのAPP_ENV環境変数を定義することで上書きできます。

環境ファイルの暗号化

暗号化してない環境ファイルは、絶対にソースコントロールで保存してはいけません。しかし、Laravelでは環境ファイルを暗号化でき、アプリケーションの他の部分と一緒にソースコントロールへ安全に追加できます。

暗号化

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

php artisan env:encrypt

env:encryptコマンドを実行すると、.envファイルが暗号化され、暗号化した内容を.env.encryptedファイルへ格納します。復号化キーはコマンドの出力として表示されますので、安全なパスワードマネージャで保存しておく必要があります。もし、自分自身で暗号化キーを指定する場合はコマンド実行時に、--keyオプションを使用してください。

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Note: 指定するキーの長さは、使用する暗号化方式で要求される鍵の長さと合わせる必要があります。デフォルトでLaravelは、３２文字のキーを必要とするAES-256-CBC暗号を使用します。コマンド起動時に、--cipherオプションを指定すれば、Laravelの暗号化でサポートする暗号を自由に指定できます。

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

php artisan env:encrypt --env=staging

復号化

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

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

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

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

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

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

設定値へのアクセス

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

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

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

実行時に設定値をセットするには、config関数へ配列で渡してください。

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

設定キャッシュ

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

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

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

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

Warning!! 開発過程の一環としてconfig:cacheコマンド実行を採用する場合は、必ずenv関数を設定ファイルの中だけで使用してください。設定ファイルがキャッシュされると、.envファイルはロードされません。したがって、env関数は外部システムレベルの環境変数のみを返すだけです。

デバッグモード

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

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

メンテナンスモード

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

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

php artisan down

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

php artisan down --refresh=15

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

php artisan down --retry=60

メンテナンスモードをバイパスする

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

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

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

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

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

Note: メンテナンスモードのシークレットは、通常、英数字とオプションでダッシュで構成されるべきです。URLの中で特別な意味を持つ文字、例えば ? の使用は避けるべきです。

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

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

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

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

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

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

php artisan down --redirect=/

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

メンテナンスモードから抜けるには、upコマンドを使います。

php artisan up

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

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

アプリケーションがメンテナンスモードの間、キューされたジョブは実行されません。メンテナンスモードから抜け、アプリケーションが通常状態へ戻った時点で、ジョブは続けて処理されます。

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

メンテナンスモードではアプリケーションに数秒のダウンタイムが必要なため、Laravelを使う開発においてはダウンタイムゼロを達成するために、Laravel VaporやEnvoyerなどの代替手段を検討してください。

Laravel 10.x 設定