設定

• はじめに
• 環境設定
  • 環境変数の種類
  • 環境設定の取得
  • 現在の環境の判別
  • 環境ファイルの暗号化
• 設定値へのアクセス
• 設定のキャッシュ
• デバッグモード
• メンテナンスモード

#はじめに

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

これらの設定ファイルでは、データベース接続情報やメールサーバー情報、アプリケーションのタイムゾーンや暗号化キーなどのコア設定値を構成できます。

#アプリケーション概要

急いでいる場合は、about Artisanコマンドでアプリケーションの設定、ドライバー、環境の概要を素早く確認できます。

php artisan about

アプリケーション概要の出力の特定のセクションだけに興味がある場合は、--onlyオプションでそのセクションを絞り込めます。

php artisan about --only=environment

または、特定の設定ファイルの値を詳しく調べたい場合は、config:show Artisanコマンドを使えます。

php artisan config:show database

#環境設定

アプリケーションが動作する環境に応じて異なる設定値を使うことはよくあります。例えば、ローカル環境では本番サーバーとは異なるキャッシュドライバーを使いたい場合などです。

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

Laravelのデフォルトの.envファイルには、ローカル環境か本番サーバーかによって異なる一般的な設定値が含まれています。これらの値はLaravelのenv関数を使ってconfigディレクトリ内の各設定ファイルから取得されます。

チームで開発している場合は、.env.exampleファイルを引き続きアプリケーションに含めることをおすすめします。例の設定ファイルにプレースホルダー値を入れることで、他の開発者が必要な環境変数を明確に把握できます。

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

.envファイルは、開発者やサーバーごとに異なる環境設定が必要なため、ソース管理にコミットすべきではありません。また、侵入者がソース管理リポジトリにアクセスした場合に機密情報が漏れるリスクもあります。

しかし、Laravelの組み込みの環境暗号化を使えば、環境ファイルを暗号化して安全にソース管理に含めることができます。

#追加の環境ファイル

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

#環境変数の種類

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

値にスペースを含む環境変数を定義する場合は、値をダブルクォーテーションで囲んでください。

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です...
}

#環境ファイルの暗号化

暗号化されていない環境ファイルはソース管理に保存すべきではありません。しかし、Laravelでは環境ファイルを暗号化して、アプリケーションと一緒に安全にソース管理に含められます。

#暗号化

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

複数の環境ファイル（例：.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コマンドを実行すると、.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ファサードやグローバルなconfig関数を使って設定値に簡単にアクセスできます。設定値はファイル名とオプション名をドットでつなぐ「ドット構文」でアクセスします。設定オプションが存在しない場合に返すデフォルト値も指定可能です：

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

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

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

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

Config::set('app.timezone', 'America/Chicago');

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

#設定のキャッシュ

アプリケーションのパフォーマンスを向上させるために、config:cache Artisanコマンドで設定ファイルをすべて1つのファイルにキャッシュしてください。これにより、設定オプションが1つのファイルにまとめられ、フレームワークが高速に読み込めます。

通常、php artisan config:cacheコマンドは本番環境のデプロイ時に実行します。ローカル開発中は設定を頻繁に変更するため、このコマンドは実行しないでください。

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

このため、env関数はアプリケーションの設定ファイル（config）内でのみ呼び出すようにしてください。Laravelのデフォルト設定ファイルを見れば多くの例が確認できます。設定値はアプリケーションのどこからでも上記のconfig関数で取得できます。

キャッシュされた設定をクリアするには、config:clearコマンドを使います：

php artisan config:clear

#デバッグモード

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

#メンテナンスモード

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

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

php artisan down

すべてのメンテナンスモードレスポンスにRefresh HTTPヘッダーを送信したい場合は、downコマンド実行時にrefreshオプションを指定できます。Refreshヘッダーは指定秒数後にブラウザに自動リロードを指示します：

php artisan down --refresh=15

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

php artisan down --retry=60

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

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

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

メンテナンスモードに入れた後、このトークンに対応するURLにアクセスすると、Laravelはブラウザにメンテナンスモードバイパスクッキーを発行します：

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

Laravelに秘密トークンを自動生成させたい場合は、with-secretオプションを使えます。メンテナンスモードに入ると秘密が表示されます：

php artisan down --with-secret

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

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

デプロイ時にphp artisan downコマンドを使うと、Composer依存関係や他のインフラが更新中にユーザーがアプリケーションにアクセスするとエラーが発生することがあります。これは、メンテナンスモードビューをテンプレートエンジンでレンダリングするためにLaravelフレームワークの多くの部分が起動する必要があるためです。

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

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

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

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

php artisan down --redirect=/

#メンテナンスモードの解除

メンテナンスモードを解除するには、upコマンドを使います：

php artisan up

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

メンテナンスモード中は、キュージョブは処理されません。メンテナンスモード解除後は通常通り処理されます。

#メンテナンスモードの代替手段

メンテナンスモードは数秒のダウンタイムが必要なため、Laravel VaporやEnvoyerのようなゼロダウンタイムデプロイを実現する代替手段を検討してください。