設定

Laravelの設定ファイル、環境変数(.env)、設定値へのアクセス方法、キャッシュ、デバッグモード、メンテナンスモードを解説します。

​

はじめに

Laravelフレームワークの設定ファイルはすべて config/ ディレクトリに格納されています。各オプションにはコメントが付いているので、ファイルを開いて利用可能なオプションを確認してみてください。

設定ファイルでは、データベース接続情報・メールサーバー情報・アプリケーションURLや暗号化キーなど、さまざまなコア設定値を管理します。

​

about コマンド

about Artisanコマンドを使うと、アプリケーションの設定・ドライバー・環境の概要を確認できます。

php artisan about

特定のセクションだけを確認したい場合は --only オプションを使います。

php artisan about --only=environment

特定の設定ファイルの値を詳しく確認するには config:show コマンドが便利です。

php artisan config:show database

​

環境設定(.env)

実行環境によって設定値を切り替えたい場合がよくあります。たとえば、ローカルと本番でキャッシュドライバーを変えたいケースなどです。

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

チームで開発する場合は、.env.example ファイルを更新しながらリポジトリに含めておくと便利です。プレースホルダー値を設定しておくことで、チームの他の開発者がどの環境変数が必要かを明確に把握できます。

​

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

.env ファイルはソースコントロールにコミットしないでください。開発者やサーバーごとに異なる設定が必要であり、リポジトリに含めるとインシデント発生時に機密情報が漏洩するリスクがあります。

ただし、Laravelには環境ファイルを暗号化する機能が組み込まれており、暗号化された状態であればソースコントロールに安全に保存できます。

​

追加の環境ファイル

アプリケーション起動時、Laravelは APP_ENV 環境変数またはCLIの --env 引数が指定されているかを確認します。指定されている場合、.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() 関数を使って値を取得できます。

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

第2引数はデフォルト値です。その環境変数が存在しない場合に返されます。

​

現在の環境を確認する

現在の環境は .env ファイルの APP_ENV 変数で決まります。App ファサードの environment メソッドで取得できます。

use Illuminate\Support\Facades\App;

$environment = App::environment();

引数を渡して特定の環境かどうかを確認することもできます。

if (App::environment('local')) {
    // ローカル環境
}

if (App::environment(['local', 'staging'])) {
    // ローカルまたはステージング環境
}

​

環境ファイルの暗号化

暗号化されていない環境ファイルはソースコントロールに保存すべきではありませんが、Laravelには環境ファイルを暗号化する機能があります。

​

暗号化

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

php artisan env:encrypt

実行すると .env が暗号化され、暗号化された内容が .env.encrypted ファイルに保存されます。復号キーはコマンドの出力に表示されるので、安全なパスワードマネージャーに保存してください。

独自の暗号化キーを指定したい場合は --key オプションを使います。

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

指定するキーの長さは、使用する暗号化方式が要求するキー長と一致させる必要があります。デフォルトでは32文字のキーが必要な AES-256-CBC が使われます。--cipher オプションを使えば、暗号化がサポートする任意の暗号方式を利用できます。

.env と .env.staging のように複数の環境ファイルがある場合は、--env オプションで暗号化対象の環境名を指定できます。

php artisan env:encrypt --env=staging

​

可読な変数名（Readable Variable Names）

環境ファイルを暗号化する際、--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 オプションを使用する場合、元の環境ファイルのコメントや空行は暗号化後の出力に含まれません。

​

可読な暗号化ファイルの更新

可読な暗号化済み環境ファイルを更新する場合、Laravelは変更のない値をそのまま保持し、元の環境ファイルに存在しなくなった変数を削除します。

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

暗号化ファイルが存在しない場合は新規作成されます。既存のファイルを更新する場合は、作成時と同じ暗号化キー・暗号方式を指定してください。復号に失敗した場合、コマンドは既存ファイルを上書きせずに失敗します。

すべての値を強制的に再暗号化したい場合は --force オプションを使います。暗号化キーの変更や、無効になった暗号化ファイルの置き換えに利用できます。

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

​

復号

環境ファイルを復号するには 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 オプションを指定します。

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

.env と .env.staging のように複数の環境ファイルがある場合は、--env オプションで復号対象の環境名を指定できます。

php artisan env:decrypt --env=staging

既存の環境ファイルを上書きするには --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/Tokyo');

実行時に設定値を変更するには Config::set() または配列を config() に渡します。

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

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

型付きの取得メソッドも用意されており、型が一致しない場合は例外がスローされます。

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

​

設定のキャッシュ

アプリケーションのパフォーマンスを向上させるには、すべての設定ファイルを1つのファイルにキャッシュします。

php artisan config:cache

このコマンドはすべての設定オプションを1つのファイルにまとめ、フレームワークが素早く読み込めるようにします。

config:cache コマンドは本番環境のデプロイプロセスの一部として実行してください。ローカル開発中は設定が頻繁に変わるため、実行しないことを推奨します。

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

このため、env() 関数は必ず config/ ディレクトリ内の設定ファイルからのみ呼び出すようにしてください。アプリケーション内の他の場所からは config() 関数を使って設定値を取得します。

キャッシュを削除するには config:clear コマンドを使います。

php artisan config:clear

​

設定ファイルの公開

Laravelの設定ファイルの多くはすでに config/ ディレクトリに公開されていますが、cors.php や view.php など一部のファイルはデフォルトでは公開されていません。

未公開の設定ファイルを公開するには config:publish コマンドを使います。

php artisan config:publish

php artisan config:publish --all

​

デバッグモード

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

本番環境では APP_DEBUG を必ず false に設定してください。 true のままにすると、アプリケーションの機密設定値がエンドユーザーに公開される危険があります。

# ローカル開発
APP_DEBUG=true

# 本番環境
APP_DEBUG=false

​

メンテナンスモード

アプリケーションがメンテナンスモードのとき、すべてのリクエストに対してカスタムビューが表示されます。これにより、アップデート中や保守作業中にアプリケーションを一時的に「無効化」できます。

​

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

php artisan down

--refresh オプションを指定すると、ブラウザが指定秒数後に自動的にリロードされます。

php artisan down --refresh=15

--retry オプションは Retry-After HTTPヘッダーの値として設定されます。

php artisan down --retry=60

​

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

シークレットトークンを使って特定のユーザーだけがアクセスできるようにするには --secret オプションを使います。

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

--with-secret オプションを使うとLaravelがトークンを自動生成します。

php artisan down --with-secret

​

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

デフォルトではLaravelはファイルベースでメンテナンスモードを管理します。複数サーバー構成の場合は、キャッシュベースの方法が便利です。

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

​

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

デプロイ中に php artisan down を実行する場合、依存関係更新中にアクセスしたユーザーがエラーを目にすることがあります。これを防ぐには --render オプションでビューを事前レンダリングします。

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

メンテナンスモード中にすべてのリクエストを特定のURLにリダイレクトすることもできます。

php artisan down --redirect=/

​

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

php artisan up

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

ダウンタイムを完全になくしたい場合は、Laravel Cloud のようなフルマネージドプラットフォームの利用を検討してください。

​

次のステップ

ルーティング

URLとコントローラーを結びつけるルーティングの基礎を学びます。