設定

はじめに

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

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

`about`コマンド

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

php artisan about

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

php artisan about --only=environment

また、特定の設定ファイルの値を詳細に確認するには、config:showアーティザンコマンドを使用できます。

php artisan config:show database

環境設定

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

これを簡単にするために、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	(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')) {
        // 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はAES-256-CBC暗号を使用しますが、--cipherオプションを使用してコマンドを呼び出す際にLaravelのencrypterでサポートされている任意の暗号を使用できます。

.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ファイルに保存します。

--cipherオプションをenv:decryptコマンドに提供することで、カスタム暗号化暗号を使用できます：

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');

    // 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:cache Artisan コマンドを使用してすべての設定ファイルを単一のファイルにキャッシュすることをお勧めします。これにより、アプリケーションのすべての設定オプションが1つのファイルに結合され、フレームワークによって迅速に読み込まれます。

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

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

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

config:clearコマンドは、キャッシュされた構成を削除するために使用できます：

php artisan config:clear

警告

デプロイプロセス中にconfig:cacheコマンドを実行する場合は、構成ファイル内でenv関数を呼び出していることを確認してください。構成がキャッシュされると、.envファイルは読み込まれなくなります。そのため、env関数は外部のシステムレベルの環境変数のみを返すようになります。

構成の公開

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

ただし、デフォルトで公開されていない構成ファイルを公開するためにconfig:publish Artisanコマンドを使用することができます：

php artisan config:publish

php artisan config:publish --all

デバッグモード

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

警告

ローカル開発では、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オプションを指定することもできます。これは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

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

注記

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

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

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

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

'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

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

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

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

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

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

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

php artisan down --redirect=/

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

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

php artisan up

注記

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

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

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

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

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

設定

はじめに​

aboutコマンド​

環境設定​

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

追加の環境ファイル​

環境変数の種類​

環境設定の取得​

現在の環境の決定​

環境ファイルの暗号化​

暗号化​

復号​

設定値へのアクセス​

設定のキャッシュ​

構成の公開​

デバッグモード​

メンテナンスモード​

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

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

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

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

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

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

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