設定と .env

アプリには、データベースのつなぎ先、メールサーバー、アプリの URL など、決めておくことがたくさんあります。Laravel では、そうした「設定」を config フォルダの中のファイルにまとめて書きます。各項目には説明が付いているので、眺めるだけでも何が決められるか分かります。手元のパソコンと本番のサーバーで値を変えたいものは、.env というファイルに書きます。

アプリの設定を一覧で見る（about と config:show）#

about という Artisan コマンド（php artisan で動かす Laravel のコマンド）を使うと、アプリの設定・ドライバー（使う方式）・環境の概要が見られます。

php artisan about

見たい部分だけに絞るときは、--only を付けます。

php artisan about --only=environment

設定ファイル1つぶんの値をくわしく見たいときは、config:show を使います。

php artisan config:show database

環境ごとの設定（.env）#

動かす場所によって、設定値を変えたいことがよくあります。たとえば、手元と本番で使うキャッシュの方式を変えたい、といった場合です。

そのために Laravel は、DotEnv という PHP のライブラリ（だれかが作って公開している、便利なプログラムの部品）を使っています。新しく作ったアプリの一番上には、よく使う環境変数（環境ごとに変える設定値）を書いた .env.example があり、インストールのときに自動で .env にコピーされます。.env に書いた値は、config フォルダの設定ファイルが env 関数で読みます。

チームで開発するなら、.env.example もアプリに入れて更新し続けるとよいでしょう。ダミーの値を入れておけば、ほかの人が「動かすにはどの環境変数が要るか」が分かります。

.env を守る#

.env は、Git など（ソースコードの変更を記録して残す道具）には入れません。理由は2つあります。1つは、開発者やサーバーごとに中身が違ってよいからです。もう1つは、もし悪い人がソースコードの置き場所に入りこんだとき、パスワードなどの秘密まで見られてしまうからです。

ただし、Laravel には環境ファイルを暗号化（鍵があれば元に戻せる形に変えること）する機能があります。暗号化したものなら、Git に入れても安全です。くわしくは、このページの後ろの「環境ファイルを暗号化する」で説明します。

環境ごとに別のファイルを読む#

Laravel は、.env を読む前に、APP_ENV という環境変数が外から渡されているか、--env という指定がコマンドに付いているかを調べます。どちらかがあれば、.env.[APP_ENV] というファイルを探して読みます。そのファイルが無ければ、いつもの .env を読みます。

値の型#

.env に書いた値は、ふつう文字列として読まれます。ただし、次の決まった言葉を書いたときだけは、env() 関数が文字列ではない値（true・false・null など）として返します。

値に空白を入れたいときは、二重引用符（"）で囲みます。

APP_NAME="My Application"

値を読み出す#

.env に書いた変数は、リクエストが来たときに PHP の $_ENV に読みこまれます。ただ、設定ファイルの中では env 関数を使って値を取ります。Laravel の設定ファイルを開くと、すでにそう書かれているのが分かります。

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

env 関数の2つ目の値は「既定値」です。その名前の環境変数が無いときに、これが返ります。

いまの環境を調べる#

いまの環境は、.env の APP_ENV で決まります。値は、App ファサード（Route::get() のようにクラス名と :: で機能を呼べる窓口）の environment メソッドで取れます。

use Illuminate\Support\Facades\App;

$environment = App::environment();

environment メソッドに値を渡すと、いまの環境がそれと同じかを調べられます。どれか1つでも合えば true を返します。

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

if (App::environment(['local', 'staging'])) {
    // 環境は local か staging のどちらか...
}

環境ファイルを暗号化する#

暗号化していない環境ファイルは、Git などに入れてはいけません。Laravel の機能で暗号化すれば、ほかのコードといっしょに Git に入れても安全になります。

暗号化する#

env:encrypt コマンドで暗号化します。

php artisan env:encrypt

.env が暗号化されて、.env.encrypted というファイルに入ります。復号（暗号を元に戻すこと）に使う鍵が画面に表示されるので、安全なパスワード管理の道具にしまっておきます。自分で決めた鍵を使いたいときは、--key を付けます。

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

.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 で作ったファイルを更新するときは、変わっていない値はそのまま残り、元の環境ファイルから消えた変数は取り除かれます。

php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

暗号化したファイルが無ければ、新しく作られます。すでにあるファイルを更新するときは、作ったときと同じ鍵と暗号方式を渡します。復号できないときは、ファイルを上書きせずに失敗します。

すべての値を暗号化し直したいときは、--force を付けます。鍵を変えたいときや、壊れたファイルを入れ替えたいときに使えます。

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

復号する#

env:decrypt コマンドで復号します。鍵は、LARAVEL_ENV_ENCRYPTION_KEY という環境変数から読まれます。

php artisan env:decrypt

--key で鍵を直接渡すこともできます。

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

実行すると、.env.encrypted の中身が復号されて、.env に書き出されます。

暗号方式を変えたときは、--cipher で指定します。

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

環境ファイルが複数あるときは、--env で復号するファイルを選びます。

php artisan env:decrypt --env=staging

すでにある環境ファイルを上書きしたいときは、--force を付けます。

php artisan env:decrypt --force

暗号化のオプションのまとめ#

設定値を取り出す#

設定値は、アプリのどこからでも、Config ファサードか config ヘルパー関数（どこからでも呼べる便利な関数）で取り出せます。値の名前は、設定ファイルの名前と項目を . でつないで書きます（ドット記法。app.timezone なら config/app.php の timezone）。項目が無いときに返す既定値も渡せます。

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 コマンドで、すべての設定ファイルを1つのファイルにまとめて取っておけます。1つにまとまっていれば、Laravel がすばやく読めます。

このコマンドは、ふつう本番へ公開する手順の中で動かします。手元で開発しているあいだは、設定をよく変えるので動かしません。

キャッシュしたあとは、リクエストの間も Artisan コマンドの間も、.env は読まれなくなります。そのため env 関数が返すのは、サーバーや OS に設定した外側の環境変数だけです。だから、env 関数は設定（config）ファイルの中だけで呼ぶようにします。それ以外の場所では、前の節の config 関数で値を取ります。

キャッシュを消したいときは、config:clear を使います。

php artisan config:clear

設定ファイルを取り出す（publish）#

Laravel の設定ファイルの多くは、はじめから config フォルダに入っています。ただし、cors.php や view.php のように、ふつうのアプリでは変える必要がないものは、はじめは入っていません。

入っていない設定ファイルを取り出したいときは、config:publish を使います。

php artisan config:publish

php artisan config:publish --all

デバッグモード#

config/app.php の debug は、エラーのときに利用者へどれだけの情報を見せるかを決めます。既定では、.env の APP_DEBUG の値に従います。

メンテナンスモード#

メンテナンスモードにすると、アプリへのすべてのリクエストに、専用の画面が返ります。アプリを更新しているあいだや、保守をしているあいだに、アプリを一時的に止めておく方法です。メンテナンス中かどうかは、アプリに最初から入っているミドルウェア（リクエストが処理に届く前に、間に入って確かめる処理）が調べます。メンテナンス中なら、Symfony\Component\HttpKernel\Exception\HttpException という例外が、ステータスコード 503（「いまは使えません」を表す番号）で投げられます。

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

php artisan down

refresh オプションを付けると、メンテナンス中のすべてのレスポンスに Refresh という HTTP ヘッダー（レスポンスに添える追加の情報）が付きます。これは、指定した秒数のあとにブラウザが自動でページを読み直すための指示です。

php artisan down --refresh=15

retry オプションに渡した値は、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

この合言葉の URL を開くと、アプリの / へ移ります。Cookie が渡されたあとは、メンテナンスモードでないときと同じようにアプリを見られます。

複数のサーバーでメンテナンスモードにする#

既定では、メンテナンスモードかどうかはファイルで決まります。そのため、アプリを置いているサーバーのすべてで php artisan down を動かす必要があります。

別の方法として、キャッシュで決める方式があります。この方式なら、php artisan down を1台で動かすだけで済みます。.env のメンテナンスモードの変数を書きかえ、すべてのサーバーから使えるキャッシュの保存先（store）を選びます。

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

メンテナンス画面を前もって作っておく#

公開の手順の中で php artisan down を使っても、Composer の部品などを更新しているあいだにアクセスした人は、エラーに当たることがあります。メンテナンス中かを調べて画面を作るのに、Laravel の大部分を起動する必要があるからです。

そこで、メンテナンス画面を前もって作っておく方法があります。この画面は、アプリの部品を読みこむ前の、リクエストのいちばん最初に返されます。down コマンドの render オプションで、使うテンプレートを選びます。

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

メンテナンス中に別の URL へ移す#

メンテナンス中は、利用者が開こうとしたどの URL にも、メンテナンスの画面が出ます。代わりに、すべてのリクエストを決まった URL へ移したいときは、redirect オプションを使います。たとえば / へ移すなら、次のようにします。

php artisan down --redirect=/

メンテナンスモードをやめる#

やめるときは、up コマンドを使います。

php artisan up

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

メンテナンスモードのあいだは、キューに入っている仕事（ジョブ）は処理されません。メンテナンスモードをやめれば、いつもどおり処理が再開されます。

メンテナンスモードに代わる方法#

メンテナンスモードでは、アプリが数秒間止まります。止めずに公開したいときは、Laravel Cloud のような、サーバーの管理をまるごと任せられるサービスで動かす方法があります。

メンテナンスモードのオプションのまとめ#

関連するページ#

• インストール
• フォルダ構成
• 暗号化
• 本番へ公開する（デプロイ）
• Artisan コマンド