EC-CUBE 4でカスタマイズをするなら最初に設定しておきたい「デバッグモード」の切り替え方です。エラーの原因がその場で分かるようになり、変数の中身を確認する dump() 関数も使えるようになります。
ルートディレクトリ直下の .env ファイルを2行書き換えるだけです。書き換えたらキャッシュを削除してください。
APP_ENV=dev
APP_DEBUG=1本番環境へ戻すときは APP_ENV=prod / APP_DEBUG=0 です。戻し忘れるとページがインデックス登録されなくなるので注意してください。
デバッグモードを設定していないと、エラーが起きても用意されたエラーページが表示されるだけで、どこで何が起きたのか分かりません。設定しておくと、エラーの発生箇所と内容が画面に出るようになります。
本番モードのエラー画面
あらかじめ用意されたエラーページが表示されるのみ
デバッグモードのエラー画面
エラーの詳細画面が表示される
デバッグモード中は、変数の中身を確認できる dump() 関数も使えるようになります。カスタマイズに必須ともいえる関数ですので、あわせて使いこなせるようにしておきましょう。
【動作環境】EC-CUBEのバージョン：4.3.0 ／ サーバー：XServer
デバッグモードの設定方法
デバッグモードは、EC-CUBEのルートディレクトリ直下にある .env ファイルを少し修正するだけで設定できます。
ファイルサーバーにアクセスし、「.env」ファイルをダウンロードします
.env ファイルの6〜9行目あたりを以下のとおり修正します。
.envファイル 修正前
# This file is a "template" of which env vars needs to be defined in your configuration or in an .env file
# Set variables here that may be different on each deployment target of the app, e.g. development, staging, production.
# https://symfony.com/doc/current/best_practices/configuration.html#infrastructure-related-configuration
###> symfony/framework-bundle ###
# For production servers, use: "APP_ENV=prod" and "APP_DEBUG=0"
# For local development, use: "APP_ENV=dev" and "APP_DEBUG=1"
APP_ENV=prod
APP_DEBUG=0
#TRUSTED_PROXIES=127.0.0.1,127.0.0.2
#TRUSTED_HOSTS=^localhost$,^example\.com$
###< symfony/framework-bundle ###.envファイル 修正後
# This file is a "template" of which env vars needs to be defined in your configuration or in an .env file
# Set variables here that may be different on each deployment target of the app, e.g. development, staging, production.
# https://symfony.com/doc/current/best_practices/configuration.html#infrastructure-related-configuration
###> symfony/framework-bundle ###
# For production servers, use: "APP_ENV=prod" and "APP_DEBUG=0"
# For local development, use: "APP_ENV=dev" and "APP_DEBUG=1"
#APP_ENV=prod
#APP_DEBUG=0
APP_ENV=dev
APP_DEBUG=1
#TRUSTED_PROXIES=127.0.0.1,127.0.0.2
#TRUSTED_HOSTS=^localhost$,^example\.com$
###< symfony/framework-bundle ###書き換える2行の意味は以下のとおりです。
| 項目 | 値 | 意味 |
|---|---|---|
| APP_ENV | prod | 本番環境として動作する |
| APP_ENV | dev | 開発環境として動作する |
| APP_DEBUG | 0 | エラー時に最小限の表示を行う |
| APP_DEBUG | 1 | エラー時に詳細表示を行う |
EC-CUBE 4.2以降は、ファイル内に本番環境（For production servers）と開発環境（For local development）の設定に関するコメントが書かれるようになりました。元の行はコメントアウトして残しておくと、戻すときに迷いません。
修正が終わったファイルをサーバーへアップし、デバッグモードの設定は終了です。念のため管理画面から キャッシュ を削除し、エラーページが変わっているか確認しておきましょう。
管理画面の「コンテンツ管理」→「キャッシュ管理」からキャッシュを削除できます
EC-CUBE 4.3.0 では、デバッグモードが有効のときに管理画面へアラートが表示されるようになりました
本番環境ではデバッグモードの解除を忘れずに
デバッグモードのままでも通常の表示はきちんと行われるので、本番環境に戻すのを意外と忘れがちです。
デバッグモードのままだと、ページがインデックス登録されないなどの問題が発生します。また、エラー時に内部のファイルパスや設定内容が画面へ出てしまうため、公開状態のまま放置しないようにしてください。
本番環境 へ戻すときは、.env を以下の状態に戻してキャッシュを削除します。
APP_ENV=prod
APP_DEBUG=0デバッグモードを解除したときにエラーが発生する場合
デバッグモードでカスタマイズを行ったあと、本番環境に戻すと稀にエラー画面が表示される場合がありました。デバッグモード中は特にエラーが出ていないにもかかわらず、です。
そんなときは、キャッシュを削除すると解消される場合があります。キャッシュは「EC-CUBE管理画面」→「コンテンツ管理」→「キャッシュ管理」から削除できます。
ただし、エラーの発生状況によってはそもそも管理画面にすら入れないパターンもあります。その場合は、ちょっと面倒ですがサーバーへSSH接続をして、ルートディレクトリに移動した状態で以下のコマンドを打ち込むとキャッシュを削除できます。
bin/console cache:clear --no-warmupSSH接続の方法については、XServer限定ですが以下の記事で解説しています。
「bin/console: 許可がありません」と表示されたら
以下のコマンドを順に実行し、権限を付与してから再度実行します。
cd bin
chmod 0704 console
cd ..PHPのバージョン要件を満たしていないと表示されたら
適切な PHP バージョンを指定してコマンドを実行します。以下はPHP 8.3を指定してキャッシュをクリアする例です。
/usr/bin/php8.3 bin/console cache:clear --no-warmupカスタマイズ時によく分からないエラーが発生した場合は、とりあえずキャッシュを削除する癖をつけておくと良さそうです。