【EC-CUBE 4】独自の定数（パラメータ）を設定・管理する方法

EC-CUBE 4で、税率や送料のしきい値といった「あちこちで使う数値」を1か所にまとめる方法です。EC-CUBEのベースである Symfony の流儀にならって YAML ファイルへ書き出します。各コードブロックの右上のボタンでそのままコピーできます。

parameters:
    custom_parameter: 1000

商品ページや コントローラー に数値を直接書き込んでいくと、あとで変更したいときに全ファイルを探して回ることになります。こうした値を1か所へ集めておくと、メンテナンス性が上がり修正漏れによるバグも防げます。

YAMLとは？

YAML（YAML Ain’t Markup Language、ヤムルまたはヤメル）は、人が読み書きしやすい形で設定値を書くためのデータ形式です。JSON と同じ用途に使われますが、記号が少なく設定ファイル向きです。

ざっくり言えば「設定値を管理するための辞書形式のファイル」です。

独自の定数を設定する手順

1. STEP1

   services.yaml を用意する

   以下の内容で services.yaml というファイルを用意し、app/Customize/Resource/config の下に置きます。

   parameters:
       custom_parameter: 1000

   キー名: 値 という形式で書きます。キー名は他の設定と衝突しないよう、独自であることが分かる名前にしておくと安全です。

   数値以外も扱えます。

   parameters:
       custom_parameter: 1000
       custom_shop_message: '本日中のご注文で翌日発送します'
       custom_free_shipping: true
       custom_campaign_tags:
           - 'summer'
           - 'sale'

   置き場所が app/Customize の下である点が重要です。app/config/eccube/packages/eccube.yaml へ追記しても動きますが、EC-CUBE本体のバージョンアップで上書きされて消える可能性があります。

2. STEP2

   キャッシュを削除する

   設定ファイルの内容は起動のたびに読み直されるわけではなく、キャッシュ として保存されています。ファイルを置いただけでは新しい定数が認識されません。

   EC-CUBE管理画面の「コンテンツ管理」→「キャッシュ管理」からキャッシュを削除します。管理画面に入れない場合は、サーバーにSSH接続してルートディレクトリで以下のコマンドを実行します。

   bin/console cache:clear --no-warmup

   「定数を追加したのに パラメータが存在しません というエラーが出る」という場合、まずここを疑ってください。本番環境（APP_ENV=prod）ではキャッシュが効いているため、削除しないかぎり反映されません。

3. STEP3

   Controllerから呼び出す

   AbstractController を継承しているクラスであれば、以下の記述で定数を取り出せます。

   $this->eccubeConfig['custom_parameter'];

   ファイル冒頭のuse宣言を忘れないようにしてください。

   use Eccube\Controller\AbstractController;

   あとは適当な変数へ代入したり、Twigテンプレートへ渡したりして活用できます。

   public function index()
   {
       $threshold = $this->eccubeConfig['custom_parameter'];
   
       return $this->render('index.twig', [
           'threshold' => $threshold,
       ]);
   }

Controller以外のクラスから呼び出す

Serviceクラスなど AbstractController を継承しないクラスでは、EccubeConfig を自分で受け取る必要があります。以下の3つを記述してください。

use Eccube\Common\EccubeConfig;

private $eccubeConfig;

/**
 * @param EccubeConfig $eccubeConfig
 * @required
 */
public function setEccubeConfig(EccubeConfig $eccubeConfig)
{
    $this->eccubeConfig = $eccubeConfig;
}

これで、Controllerと同じように $this->eccubeConfig['custom_parameter'] で値を取り出せます。

Twigテンプレートから呼び出す

Controllerを経由せず、Twigテンプレートから直接参照することもできます。EC-CUBEは app/config/eccube/packages/twig.yaml で eccube_config をグローバル変数として登録しているため、どのテンプレートからでも使えます。

{{ eccube_config['custom_parameter'] }}

条件分岐に使うこともできます。

{% if Order.total >= eccube_config['custom_parameter'] %}
    <p>送料無料の対象です</p>
{% endif %}

Twigの記法そのものについては、以下の記事にまとめています。

開発環境と本番環境で値を変える

「テスト中は送料無料のしきい値を0円にしておきたい」というように、環境ごとに違う値を使いたい場合があります。EC-CUBEは services.yaml に加えて、環境名の付いたファイルも読み込みます。

同じキーを両方に書いた場合、あとから読み込まれる環境別ファイルの値が使われます。つまり services.yaml に既定値を書いておき、開発環境だけ services_dev.yaml で上書きする、という使い方ができます。

parameters:
    custom_parameter: 0

上記を app/Customize/Resource/config/services_dev.yaml として置けば、開発環境 のときだけしきい値が0になります。

定数が反映されないときの確認ポイント

設定したはずの定数が読み込まれない場合、原因はほぼ以下の4つに絞られます。

ファイルの位置とファイル名は、EC-CUBE本体が読み込み対象を決め打ちしているため、少しでもずれていると黙って無視されます。エラーが出ないぶん気づきにくいので、まずここを見てください。

まとめ

EC-CUBEで独自の 定数 を管理する方法をまとめました。

• app/Customize/Resource/config/services.yaml に parameters: で書く
• 保存したらキャッシュを削除する。これを忘れると反映されない
• Controllerからは $this->eccubeConfig['キー名']
• Twigからは {{ eccube_config['キー名'] }}
• 環境ごとに値を変えたいときは services_dev.yaml / services_prod.yaml

ひとつ設定を移すだけでも、後々の修正がぐっと楽になります。数値を直接書き込んでいる箇所を見つけたら、少しずつ移していくのがおすすめです。

EC-CUBEのカスタマイズに関する記事

• カスタマイズのまとめ
• Twig まとめ(1) ～継承やブロックについて～
• デバッグモードの設定/解除方法
• 変数の中身を確認する方法（dump関数）

この記事に出てきた用語

• YAMLとは？
• 定数とは？
• Symfonyとは？
• コントローラーとは？
• キャッシュとは？