バージョン: master

構成 (Configuration)

Introduction
環境構成
構成値へのアクセス
構成のキャッシュ
設定の公開
デバッグモード
メンテナンスモード

導入 (Introduction)

Laravel フレームワークの構成ファイルはすべて、config ディレクトリに保存されます。各オプションは文書化されているので、ファイルに目を通して、利用可能なオプションをよく理解してください。

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

`about` コマンド

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

php artisan about

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

php artisan about --only=environment

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

php artisan config:show database

環境構成 (Environment Configuration)

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

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

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

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

.env ファイル内の変数は、サーバーレベルまたはシステムレベルの環境変数などの外部環境変数によってオーバーライドできます。

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

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

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

追加の環境ファイル

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

環境変数のタイプ

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

`.env` 値	`env()` 値
真実	(ブール値) true
（真実）	(ブール値) true
間違い	(ブール値) false
（間違い）	(ブール値) false
空の	（弦） ''
（空の）	（弦） ''
ヌル	(ヌル)ヌル
(ヌル)	(ヌル)ヌル

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

APP_NAME="My Application"

環境設定の取得

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

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

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

現在の環境を判断する

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

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

if (App::environment('local')) {
    // The environment is local
}

if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

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

環境ファイルの暗号化

暗号化されていない環境ファイルはソース管理に保存しないでください。ただし、Laravel を使用すると、環境ファイルを暗号化して、アプリケーションの残りの部分とともにソース管理に安全に追加できるようになります。

暗号化

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

提供されるキーの長さは、使用されている暗号化方式で必要なキーの長さと一致する必要があります。デフォルトでは、Laravel は 32 文字のキーを必要とする AES-256-CBC 暗号を使用します。コマンドを呼び出すときに --cipher オプションを渡すことで、Laravel の encrypter でサポートされている暗号を自由に使用できます。

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

php artisan env:encrypt --env=staging

読み取り可能な変数名

環境ファイルを暗号化する場合、--readable オプションを使用して、値を暗号化しながら表示される変数名を保持できます。

php artisan env:encrypt --readable

これにより、次の形式の暗号化されたファイルが生成されます。

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

読み取り可能な形式を使用すると、機密データを公開することなく、どの環境変数が存在するかを確認できます。また、ファイルを復号化することなく、どの変数が追加、削除、または名前変更されたかを確認できるため、プルリクエストのレビューが非常に簡単になります。

環境ファイルを復号化するときに、Laravel は使用された形式を自動的に検出するため、env:decrypt コマンドに追加のオプションは必要ありません。

--readable オプションを使用する場合、元の環境ファイルのコメントと空白行は暗号化された出力に含まれません。

復号化

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

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

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

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

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

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

構成値へのアクセス (Accessing Configuration Values)

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

use Illuminate\Support\Facades\Config;

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

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

// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');

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

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

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

静的分析を支援するために、Config ファサードは、型付き構成の取得メソッドも提供します。取得した構成値が予期されるタイプと一致しない場合、例外がスローされます。

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');

構成のキャッシュ (Configuration Caching)

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

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

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

このため、アプリケーションの構成 (config) ファイル内からのみ env 関数を呼び出していることを確認する必要があります。 Laravel のデフォルト設定ファイルを調べると、この例を数多く確認できます。構成値には、config 関数上で説明したを使用して、アプリケーション内のどこからでもアクセスできます。

config:clear コマンドを使用して、キャッシュされた構成を削除できます。

php artisan config:clear

デプロイメントプロセス中に config:cache コマンドを実行する場合は、構成ファイル内からのみ env 関数を呼び出していることを確認する必要があります。構成がキャッシュされると、.env ファイルはロードされません。したがって、env 関数は、外部のシステムレベルの環境変数のみを返します。

設定の公開 (Configuration Publishing)

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

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

php artisan config:publish

php artisan config:publish --all

デバッグモード (Debug Mode)

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

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

メンテナンスモード (Maintenance Mode)

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

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

php artisan down

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

php artisan down --refresh=15

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

php artisan down --retry=60

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

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

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

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

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

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

php artisan down --with-secret

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

メンテナンスモードのシークレットは通常、英数字と、必要に応じてダッシュで構成されます。 URL では、? や & などの特別な意味を持つ文字を使用しないでください。

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

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

あるいは、Laravel はメンテナンスモードを処理するためのキャッシュベースの方法を提供します。この方法では、1 つのサーバー上で php artisan down コマンドを実行する必要があります。このアプローチを使用するには、アプリケーションの .env ファイル内のメンテナンスモード変数を変更します。すべてのサーバーからアクセスできるキャッシュ store を選択する必要があります。これにより、メンテナンスモードのステータスがすべてのサーバーにわたって一貫して維持されます。

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

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

デプロイメント中に 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

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

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

アプリケーションがメンテナンスモードの間は、キューに入れられたジョブは処理されません。アプリケーションがメンテナンスモードを終了しても、ジョブは通常どおり処理され続けます。

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

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

導入 (Introduction)​

about コマンド​

環境構成 (Environment Configuration)​

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

追加の環境ファイル​

環境変数のタイプ​

環境設定の取得​

現在の環境を判断する​

環境ファイルの暗号化​

暗号化​

読み取り可能な変数名​

復号化​

構成値へのアクセス (Accessing Configuration Values)​

構成のキャッシュ (Configuration Caching)​

設定の公開 (Configuration Publishing)​

デバッグモード (Debug Mode)​

メンテナンスモード (Maintenance Mode)​

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

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

メンテナンス モード ビューのプリレンダリング​

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

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

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

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

導入 (Introduction)

`about` コマンド

環境構成 (Environment Configuration)

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

追加の環境ファイル

環境変数のタイプ

環境設定の取得

現在の環境を判断する

環境ファイルの暗号化

暗号化

読み取り可能な変数名

復号化

構成値へのアクセス (Accessing Configuration Values)

構成のキャッシュ (Configuration Caching)

設定の公開 (Configuration Publishing)

デバッグモード (Debug Mode)

メンテナンスモード (Maintenance Mode)

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

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

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

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

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

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

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