イントロダクション
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
関数に渡す2番目の値は「デフォルト値」です。指定されたキーの環境変数が存在しない場合、この値が返されます。
現在環境の決定
現在のアプリケーション環境は、.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は、32文字のキーを必要とする
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つのファイルへキャッシュする必要があります。これにより、アプリケーションのすべての設定オプションが1ファイルに結合され、フレームワークによってすばやくロードされます。
通常、本番デプロイメントプロセスの一部としてphp artisan config:cache
コマンドを実行する必要があります。アプリケーションの開発中は設定オプションを頻繁に変更する必要があるため、ローカル開発中はコマンドを実行しないでください。
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に対し、メンテナンスモードビューを表示します。お望みならば、全リクエストを特定のURLへリダイレクトすることも可能です。redirect
オプションを使用してください。例として、全リクエストを/
のURIへリダイレクトするとしましょう。
php artisan down --redirect=/
メンテナンスモードの無効化
メンテナンスモードから抜けるには、up
コマンドを使います。
php artisan up
Note:
resources/views/errors/503.blade.php
を独自に定義することにより、メンテナンスモードのデフォルトテンプレートをカスタマイズできます。
メンテナンスモードとキュー
アプリケーションがメンテナンスモードの間、キューされたジョブは実行されません。メンテナンスモードから抜け、アプリケーションが通常状態へ戻った時点で、ジョブは続けて処理されます。
メンテナンスモードの代替
メンテナンスモードではアプリケーションに数秒のダウンタイムが必要なため、Laravelを使う開発においてはダウンタイムゼロを達成するために、Laravel VaporやEnvoyerなどの代替手段を検討してください。