【EC-CUBE 4】注文内容に新しい項目を追加し、注文画面をカスタマイズしてみた

注文ごとに独自の情報を持たせたい、というのはよくある要望です。EC-CUBEの注文情報は dtb_order テーブルに保存されますが、ここへ自分で決めた項目をひとつ足し、注文画面のフォームから保存できるようにするまでを通しで解説します。例として「領収書が必要／不要」のチェックボックスを設置します。

このカスタマイズでやること

作業は次の3つに分かれます。どのファイルを触るのかを先に押さえておくと、途中で迷いません。

1. 1dtb_order テーブルに新規プロパティを追加（拡張）する
2. 2入力フォームを拡張（OrderTypeExtensionを作成）する
3. 3Twigテンプレートにフォームと表示用のコードを追記する

必要に応じて、注文受付メールや受注管理画面にも表示用のコードを追記します（本記事では割愛します）。

dtb_orderテーブルに新規プロパティを追加（拡張）する

まずは注文情報を保存しておくテーブル dtb_order に、独自のプロパティ receipt を追加します。EC-CUBEでは既存のエンティティをTraitで拡張することで、コアのファイルを書き換えずに項目を増やせます。

Orderエンティティを拡張する（OrderTraitの作成）

以下のTraitファイルを作成し、app/Customize/Entity 下に保存します。

<?php

namespace Customize\Entity;

use Doctrine\ORM\Mapping as ORM;
use Eccube\Annotation\EntityExtension;

/**
 * @EntityExtension("Eccube\Entity\Order")
 */
trait OrderTrait
{
    /**
     * @var boolean
     *
     * @ORM\Column(name="receipt", type="boolean", nullable=false, options={"default": false})
     */
    private $receipt = false;

    /**
     * Set receipt.
     *
     * @param boolean $receipt
     *
     * @return Order
     */
    public function setReceipt($receipt = false)
    {
        $this->receipt = $receipt;

        return $this;
    }

    /**
     * Get receipt.
     *
     * @return boolean
     */
    public function getReceipt()
    {
        return $this->receipt;
    }
}

サーバーにSSH接続してテーブル拡張

Traitファイルをアップしたら、SSH接続して以下のコマンドを順に実行し、データベースを拡張します。Traitを置いただけではEC-CUBE側がプロパティを認識しないため、この3つはセットです。

1. STEP1
   Proxyを生成する

   bin/console eccube:generate:proxies

   Traitに書いた内容を、EC-CUBEがエンティティの一部として扱えるようにするための生成処理です。

2. STEP2
   キャッシュを削除する

   bin/console cache:clear --no-warmup

   古い定義が残っていると、生成したProxyが読まれません。

3. STEP3
   データベースへ反映する

   bin/console doctrine:schema:update --dump-sql --force

   実行されるSQLを表示したうえで、データベースへ反映します。問題なく終われば、dtb_order テーブルに receipt というプロパティができているはずです。

入力フォームを拡張（OrderTypeExtensionを作成）する

続いて、追加したプロパティ receipt に値をセットするためのフォームを、注文画面（/shopping）に設置します。

注文のためのフォームにはOrderTypeが用意されており、すでに注文画面でフォームが埋め込まれています。そこで、OrderTypeを拡張したOrderTypeExtensionを作成し、app/Customize/Form/Extension 下に保存します。

<?php

namespace Customize\Form\Extension;

use Eccube\Form\Type\Shopping\OrderType;
use Symfony\Component\Form\AbstractTypeExtension;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\Extension\Core\Type\CheckboxType;

class OrderTypeExtension extends AbstractTypeExtension
{
  public static function getExtendedTypes(): iterable
  {
    return [OrderType::class];
  }

  public function buildForm(FormBuilderInterface $builder, array $options)
  {
    if (!$options['skip_add_form']) {
      $builder
      ->add('receipt', CheckboxType::class, [
        'label' => '領収証が必要な方はチェックを入れてください。',
        'required' => false,
        'mapped' => true,
      ]);
    }
  }
}

Twigテンプレートをカスタマイズする

作成したフォームを表示させるには、本来ならControllerからTwigテンプレートへフォームを渡す処理が必要です。ただし今回は、すでに既存のShoppingControllerからOrderTypeのフォームが渡されているため、Controllerのカスタマイズは不要です。

注文画面に対応するTwigテンプレート Shopping/index.twig を開き、チェックボックスを表示させたい箇所に以下を追記します。

{{ form_widget(form.receipt) }}

続いて、注文確認画面 Shopping/confirm.twig で、チェックに応じた内容を表示させます。適当な場所に以下を追記してください。

{{ Order.receipt ? '領収書：必要' : '領収書：不要' }}

見た目は、好みに応じてレイアウトやスタイルを調整してください。

実装結果

注文画面（/shopping）に、チェックボックスが設置されました。今回はお支払い方法の下に置いています。

注文確認画面（/shopping/confirm）の表示は、チェックの有無で切り替わります。

あわせて、dtb_order テーブルの receipt プロパティの値も、チェックの有無に応じて変化します。

うまくいかないときの確認ポイント

まとめ

• 注文情報への項目追加は、app/Customize/Entity に置くTraitで行う。コアのファイルは触らない
• 反映にはProxyの生成・キャッシュの削除・データベースへの反映の3コマンドが必要
• フォームの追加はOrderTypeExtension。skip_add_form が有効なときは項目を足さないのが必須条件
• 注文画面のフォームはShoppingControllerから渡されているので、Controllerのカスタマイズは不要
• 表示は、入力画面が form.receipt、確認画面が Order.receipt

あわせて読みたい
EC-CUBE 4 カスタマイズのまとめ
EC-CUBE 4について、筆者自身が学習・実践してきたカスタマイズ方法をまとめています。はじめて触る方向けに、手を動かす順番も並べました。

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

• カスタマイズのまとめ
• 既存テーブルに新しいフィールド（カラム）を追加する
• FormExtensionを使ったFormTypeのカスタマイズ
• ドロップダウンリスト / ラジオボタン / チェックボックスの実装方法
• 商品登録にオリジナルの新規項目を追加する
• デバッグモードの設定/解除方法
• 遭遇したエラー＆対処法まとめ

この記事に出てきた用語

• EC-CUBEとは？
• エンティティとは？
• ORMとは？
• データベースとは？
• ブール値（真偽値）とは？
• SSHとは？
• キャッシュとは？