【EC-CUBE】FormTypeを使ったフォームの作成

この記事の目的

EC-CUBEのカスタマイズを行う際によく使われる「FormType」について
私はEC-CUBEで開発を行って日が浅く、twigファイルにフォームの定義が記述されておらず困惑した経験がありますので「そもそもFormTypeってなにか？」「どうやって使うのか」を備忘録と学習を兼ねて記述していこうかなと思います！

FormTypeとは？

• Symfonyの「フォーム構築クラス」で、フォームの定義をView側ではなくPHP側で行うことができます
• 入力フォームの構造・バリデーション・デフォルト値などをPHPのコードで定義することが可能
• Twigテンプレート(View)に渡されて、form_widget()などで描画されます

FormTypeの基本構成

class MyFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('name', TextType::class, [
                'label' => 'お名前',
                'required' => true,
                'attr' => ['placeholder' => '名前を入力してください'],
            ])
            ->add('email', TextType::class, [
                'label' => 'メールアドレス',
                'required' => true,
            ]);
    }
}

• buildFormメソッドでフォームに表示する項目(フィールド)を定義します
• $builder->add('name', TextType::class, [ でnameという名前の入力欄を追加
  TextTypeの他に「TextareaType」「PasswordType」「EmailType」「ChoiceType」など表示させたいフォームを設定
• 'label' => 'お名前' でラベルの文言を設定
• 'required' => true で必須項目かどうかを設定
• 'attr' => ['placeholder' => '名前を入力してください'] でplaceholderの設定を行うことが可能です

よく使う add() のオプション例

• label: フィールドのラベル
• required: 必須入力かどうかを定義します
• attr: placeholderやclassなどHTML属性を指定(複数指定することが可能です)
• constraints: バリデーションルール
• choices: 配列形式でセレクトボックスの定義が行えます
  choices オプションは ChoiceType, EntityType など、選択肢を持つフィールド専用のオプションです。

Twigでの表示方法

FormTypeクラスで定義したフォームは、Twigテンプレートで form_* 関数を使って表示します

• form_start(form)
  formタグの開始を出力(action,method,csrf_tokenなども含む)
• form_row(form.xxx)
  ラベル、入力欄、エラーメッセージをまとめて出力する
• form_widget(form)
  入力欄だけを出力
  form_widget(form.xxx) は「xxx フィールドの入力欄のみ」、form_widget(form) は「フォーム全体の入力欄をまとめて出力」します。
• form_label(form.xxx)
  ラベルだけを出力
• form_errors(form.xxx)
  エラーメッセージだけを出力
• form_end(form)
  /formタグの終了を出力

まとめ

最初、Twigファイルの中にフォームの input や form が全然見当たらなくて、「どこでフォーム作ってるの？」と本気で混乱しました……。
調べてみると、EC-CUBEではフォームの構造やルールは PHP側の「FormType」クラスで定義されていて、Twig側では form_* 関数で「呼び出すだけ」になっていました。

この構造に慣れると、

• バリデーションや初期値の管理がPHPで一元化できる
• Twigがスッキリして読みやすい
  というメリットがあることに気付きました。

自分と同じように困っている人の参考になれば幸いです！