CakePHP4の.envを掘り下げてみる

CakePHP4には設定ファイルに分類されるものがいくつかあります。

config/.env
config/app.php
config/app_local.php
config/bootstrap.php

この4つがその設定ファイルに相当するものです。
config/bootstrap.phpは設定ファイル…？という感じはありますが。

一番上の.envに関しては必ず使用しなくてはならないということはありません。
事実、デフォルトではconfig/bootstrap.phpの方で「使用しない」設定になっています。
その他のファイルに関しては「ほぼ」必須です。必ず使います。

とりあえず今回は.envに関して掘り下げてみます。

そもそも.envファイルとは何なのか

Dotenvなんて書き方もされますが、一言で書くと環境変数の設定ファイルです。
Linuxなんかでよく使うアレですね。というかMacでもWindowsでもありますね。

要は「このCakePHP4で作られたプロジェクトをこんな設定値で動かします」という元ネタが書かれているファイルです。

冒頭で書いた「都合がいい理由」なんですが、.envは環境変数の設定ファイルですので実行環境が変わった場合でも記載した設定値を変更するだけで簡単に切り替えができる点が一番の理由です。

ただ環境変数ですので、.envを使わずにApacheの設定に書いても同様の役割を果たすことができます。いわゆるSetEnvってやつです。

CakePHP2を触っていた頃は.envが実装されていなかったので、Apacheの設定にSetEnvで環境変数を書いてCakePHP側からenv関数で呼ぶ運用をしたこともありました。

しかし時は流れて、CakePHP3辺りから.envが導入されました。
ですので、Apacheの設定に書かずに.envファイルの方へ必要なキーと値を記載。
それをapp.phpやapp_local.phpでenv関数を使って呼んでという方式が可能になっています。

よっぽどの理由があるなら話は別ですが、なるべくなら.envでの運用をした方が後々幸せになれるんじゃないかなと思います。
というかよっぽどの理由とやらがさっぱり思いつきません。

.env.exampleとやなんぞや

このファイルは.envを作成するためのテンプレートファイルになっていて、env.exampleをコピーして.envにリネームすることで.envファイルを作成することができます。

恐らく、CakePHP4でプロジェクトを作成した直後は.envファイルは存在しないと思います。
その代わりに.env.exampleというファイルがあるはずです。

使い方としては、この.env.exampleの中にプロジェクト内で使用する環境設定キーの雛形を定義しておいて開発環境、場合によってはステージングや本番環境で環境設定キーに相当する設定値を記載するわけです。

注意して頂きたいのはテンプレートファイルですので、例えばステージング環境時の設定や本番環境の設定を予め記載してコメントアウトしておくという運用はしないということです。
というかしてはダメです。

.env.exampleは通常git管理対象ファイルですので、うっかりGitHubなんかで公開してしまうと全世界にDB接続情報なんかがフルオープンになってしまいます。

その辺は別途管理するようにして、設定キーはともかく設定値はダミーでも入れておくといいかと思います。

.env.exampleの中身を見てみる

.env.exampleの中には以下の環境変数が最初から定義されています。
テンプレートですからそりゃそうだという話ではありますが。

export APP_NAME="__APP_NAME__"
export DEBUG="true"
export APP_ENCODING="UTF-8"
export APP_DEFAULT_LOCALE="en_US"
export APP_DEFAULT_TIMEZONE="UTC"
export SECURITY_SALT="__SALT__"

きっとこんな感じに定義されています。
もしかしたらCakePHP4のバージョンによっては増減しているかもしれませんが、その辺は読み換えるなりググるなりしてください。

一番上のAPP_NAMEを例にすると、前述していた設定キーがAPP_NAMEになり、設定値が__APP_NAME__になります。

よくあるKey-Valueの話です。
ここで定義されているキーに設定された値が環境変数になるわけです。

.envのAPP_NAMEはプロジェクト名

そのままなんですが、動作させるプロジェクト名をここに設定します。

設定したプロジェクト名はキャッシュファイルとか、プロジェクトの中から参照して表示したりとかそういう使い方をします。
これから作成するプロジェクト名を入れておくといいかと思います。

今回のサンプルとして以下のように設定してみます。

export APP_NAME="CakeSample"

ネーミングセンスの無さはとりあえず置いておきます。

.envのDEBUGはデバッグモード

これも割とそのままなんですが、デバッグモードの判定値です。

デバッグモードはconfig/app.phpの方で設定できます。
要はそこに埋め込む設定の話ですね。何てことはないです。

trueはデバッグモード、falseはデバッグモード解除を示します。
trueにしておくと、画面側でDebugKitが表示されるようになります。
他の使い方も色々あるんですが、ここでは一旦割愛します。

とりあえずデバッグモード有効にしておきましょう。

export DEBUG="true"

これでデバッグモードになるはずです。

.envのAPP_ENCODINGはエンコード

そのままなのばかりですね。これはエンコード設定です。

UTF-8以外をどうしても使いたければお好きなように変更して下さい。
でも大抵の場合は変更不要じゃないかと思います。

export APP_ENCODING="UTF-8"

設定変更せず、そのままにしておきます。

.envのAPP_DEFAULT_LOCALEはロケール設定

自分はここを変更しないのですが、ロケール設定値になります。

地域化とかいうのですが、プロジェクトを動かす国に適応させるための設定です。
メッセージが日本語化されたりとかそういう感じです。

これだけ聞くと日本に適応させた方がよさそうに思えますが、多言語化ファイルが必要でして。
それが面倒なので自分は設定しないというだけの話です。
と、エラーメッセージを日本語化させると調べるのに時間がかかるデメリットもあります。

ここは好みの話ですので、もしロケールを日本にしたい場合は以下のように変更して下さい。

export APP_DEFAULT_LOCALE="ja_JP"

今回はロケールを変更しないことにするので、設定値も以下のようにそのままにしておきます。

export APP_DEFAULT_LOCALE="en_US"

.envのAPP_DEFAULT_TIMEZONEはタイムゾーン

これもまたそのままですね。プロジェクトのタイムゾーンが設定できます。

デフォルトはUTC時刻になっています。
日本で展開するサービスであれば、UTCは都合が悪いはずですので変えてしまいましょう。

export APP_DEFAULT_TIMEZONE="Asia/Tokyo"

もちろん、UTCのままの方が都合よければ変更不要です。

.envのSECURITY_SALTはハッシュキー

ハッシュキーという言葉が若干アレなのですが、プロジェクトで使用する暗号化 / 複合化のキーになったりハッシュ文字列生成時に使用したりします。

デフォルトは「__SALT__」なんて文字列が入ってますが、これは「__SALT__という文字を暗号化 / 複合化なんかに使うキーにするぜ」という設定です。
まぁあんまりよろしくないのはわかるかと思います。

ちなみにこのSALT値を「__SALT__」から変更しなかった場合、以下のような注意メッセージが出ます。

Notice (1024): Please change the value of 'Security.salt' in ROOT/config/app.php to a salt value specific to your application. [CORE/src/Error/Debugger.php, line 1050]

config/app.phpが表示されていますが、実際にSALT値を読み込む場所がconfig/app.phpであることが理由です。
要はSALT値がデフォルトのダミー文字列のままだから変えてな！ということです。

設定する値ですが、まぁなんでもいいです。
目安としては32桁以上で大体64文字ぐらいですので、ランダム文字列を生成するのがよろしいかと思います。

本来は変更するのですが、前述したように.env.exampleはテンプレートファイルですので実際に使用するSALT値をテンプレートとして設定するのはよくありません。
今回はテンプレートの方を設定していますので、ここは変更しなくて構いません。

export SECURITY_SALT="__SALT__"

実際に設定する時はランダム文字列にしましょう。
ランダム文字列を生成するWebサービスなんかがありますので、お好きなものを。

出来上がった.env.exampleを確認してみる

さて、大した修正も必要ありませんでしたが、恐らくこんな感じの.env.exampleが出来上がったかと思います。

export APP_NAME="CakeSample"
export DEBUG="true"
export APP_ENCODING="UTF-8"
export APP_DEFAULT_LOCALE="en_US"
export APP_DEFAULT_TIMEZONE="Asia/Tokyo"
export SECURITY_SALT="__SALT__"

何度も書きましたがテンプレートファイルですので、ここにコメントを入れておくと未来の誰かが幸せになれるかもしれません。
例えばこんな風に。

# サービス名
export APP_NAME="CakeSample"

# デバッグモード(true：有効 / false：無効)
export DEBUG="true"

# エンコード設定(変更不要)
export APP_ENCODING="UTF-8"

# ロケール設定(変更不要)
export APP_DEFAULT_LOCALE="en_US"

# タイムゾーン設定(変更不要)
export APP_DEFAULT_TIMEZONE="Asia/Tokyo"

# SALT値(実行環境に応じて設定すること)
export SECURITY_SALT="__SALT__"

コメントが冗長なのは承知していますが、例えばこんな感じに。
ここまででデフォルトで用意されている.env.exampleの設定は終わりです。

.envを作成する

前述しましたが、config/.envファイルはこれまでの流れで定義したconfig/.env.exampleをコピー、リネームして作成します。

コピーせずにリネームだけでもできなくはありませんが、それだとテンプレートファイルの意味がありません。
且つ、config/.env.exampleは通常git管理対象ファイルですのでその辺も都合悪いです。

コピーリネームに特筆すべきことはないので、作成したconfig/.env.exampleをコピーしてそのファイルをconfig/.envにリネームしてあげてください。

.env使用を有効化する

config/.envを有効化する際はconfig/bootstrap.phpを修正する必要があります。
これも冒頭に書いたのですが「デフォルトでは使用しない設定になっている」ためです。
修正とは言っても、単にコメントアウトされている部分を解除するだけです。

config/bootstrap.phpを開くと以下のような部分が記載されています。

// if (!env('APP_NAME') && file_exists(CONFIG . '.env')) {
//     $dotenv = new \josegonzalez\Dotenv\Loader([CONFIG . '.env']);
//     $dotenv->parse()
//         ->putenv()
//         ->toEnv()
//         ->toServer();
// }

この部分です。
まるっとコメントアウトされているので、この箇所のコメントアウトを解除しましょう。
そうすると.envの使用が有効化されます。

まとめ

ここまでがconfig/.env.exampleに設定値を定義、config/.envを作成して有効化して使うという一連の流れになります。

ダラダラと書いてますが実際にやってみると数分で終わる作業だったりします。
よくよく考えれば、CakePHP4を使ったプロジェクトの環境変数の話ですし、そこまで時間をかけるものでもありません。

今回はデフォルトで用意されているconfig/.envの設定だけにフォーカスしましたが、ただの環境変数ですので必要あればいくらでも増やせます。
自分は割と増やす方なのですが、好き嫌いもあるんじゃないかなとも思います。

書こうかなと思ったのですが、長くなってきたのでそれはまた別記事で。
以上がCakePHP4の.env設定方法になります。

お疲れ様でした。