【EC-CUBE4】カスタマイズの始め方 – サルでもわかる初歩の初歩

2021.01.23

EC-CUBE4はSymfonyというフレームワークを基に作られており、Symfonyへの理解がない人がカスタマイズを始めようとすると何から手を付ければ良いか全くわからないという事態になりがちです。

ここではPHPの知識はあるけどSymfonyや似たようなフレームワークの知識に乏しい人に向けてカスタマイズの初歩の初歩をまとめてみます。

わかりやすさを重視して多少正確性を欠く表現や説明も含まれますが、とりあえずカスタマイズの第一歩を踏み出したいという方に向けて記します。

カスタマイズの種類

EC-CUBEをカスタマイズする場合には大きく分けて以下の3つの方法が挙げられます。

  • 本体をカスタマイズする
  • Customizeディレクトリを使う
  • プラグインを作成する

それぞれ簡単に説明します。

本体をカスタマイズする

その名の通り、EC-CUBEを構成しているソースファイルを直接修正する方法です。

最も直接的・直感的でアナログな方法と言えます。

テスト環境でカスタマイズを試してみる場合には、ここから始めても良いでしょう。

しかし、実際にECサイトを構築するとなった場合には注意が必要になります。

EC-CUBEはバグ修正やセキュリティ対策などのために時々バージョンアップが行われます。

基本的にバグやセキュリティホールへの対策ということで無視するのは現実的ではありません。

しかし、単純にバージョンアップすると本体のカスタマイズが新しいバージョンのソースコードで上書きされてしまう場合があります。

そのため本体をカスタマイズした場合には、バージョンアップのたびに既存のコードとバージョンアップ後の競合をうまく解決する必要があります。

Customizeディレクトリを使う

EC-CUBEをインストールしたディレクトリを確認するとappディレクトリ配下にCustomizeディレクトリがあることが確認できるはずです。

このディレクトリはその名の通りEC-CUBEをカスタマイズするために使用されるディレクトリです。

EC-CUBEを実行する時、Customizeディレクトリ内のファイルは本体のファイルより優先的に読み込まれます。

例えばEC-CUBEのトップページを表示するためのphpファイルをCustomizeディレクトリにコピーして内容を修正したとします。

そうするとCutomizeディレクトリにコピーして修正したphpファイルが優先的に選択されます。

実行時にCustomizeディレクトリの内容で本体のソースコードを上書きしていると言った方がイメージが掴みやすいかもしれません。

この場合、本体を直接カスタマイズした場合と違ってバージョンアップをしてもカスタマイズした内容が影響を受けません。

プラグインを作成する

EC-CUBEにはプラグインという便利な機能があります。

無償・有償でプラグインが提供されており、便利な機能を追加することができます。

基本的にCustomizeディレクトリを使ったカスタマイズと似たようなことをするのですが、最も複雑になるので今回は省略します。

Customizeディレクトリを使う方法とプラグインはどちらが良いか判断に悩むこともあるかもしれませんが、不特定多数に提供したり、機能自体の追加・削除が必要な場合にはプラグインにすると良いでしょう。

EC-CUBE本体のソースコードの確認と変更

それでは早速EC-CUBE本体のソースコードを探してみましょう。

EC-CUBEのインストールディレクトリにあるsrcディレクトリの中にあるEccubeディレクトリがEC-CUBEの本体のソースコードの在り処です。

フレームワークの知識がなくても、PHPに触れたことがある人なら「MVC」という単語を聞いたことがあるかもしれません。

簡単に言えば、ソースコードをM（Model）、Ｖ（View）、C（Controller）という3つに分割して開発する設計手法です。

その中でもカスタマイズ時に最もよく触れられるのがC（Controller）です。

コントローラーと言う名前からもわかる通り、データや表示を司る重要な部分です。

EC-CUBEのコントローラーがどこにあるかと言うと、先ほど説明したsrc/Eccubeディレクトリの中にあるControllerディレクトリの中にあります。

Controllerディレクトリの中にはTopController.phpというファイルがあるはずです。

これはEC-CUBEのトップページを表示するためのコントローラーです。

内容がスカスカでピンとこない人も多いはずです。

しかし、ここにはいくつか重要な要素が含まれています。

    /**
* @Route("/", name="homepage")
* @Template("index.twig")
*/
public function index()
{
return [];
}

まず始めにindexメソッドの前にあるコメントらしきものに注目してください。

@Routeと@Templateという記述がなんだか意味ありげですね。

これはコメントではなく「アノテーション」と呼ばれるものです。

@Routeでは、”/”とnameとして”homepage”が指定されています。

これはサイト上の”/”にアクセスがあったときにこのメソッド（indexメソッド）を実行することを示しています。

“/”というのはトップページを指しています。

nameで指定しているのはその呼び名で、他のページからリダイレクトする際などにこの呼び名を使用します。

@Templateでは.twigという見慣れない拡張子のファイルを指定していますね。

これはEC-CUBE（というかSymfony）の表示に使われる専用のファイルです。

ピュアなPHPを使った開発では、echoや<?=出力する文字列?>のような記述を使って画面を表示しますが、EC-CUBE（というかSymfony）ではTwigを利用します。

Twig – Wikipedia

Twigは画面を表示させるためのテンプレートを記述する手法のようなものです。

実際にはechoで画面を出力しても何も変わりませんが、EC-CUBE（というか）ではTwigというちょっと違った書き方をしていると覚えておいてください。

ちなみにここで指定されているindex.twigがどこにあるかというと、src/Eccube/Resource/template/defaultディレクトリ内にあります。

表示の流れを説明すると以下のようになっています。

  1. サイトにアクセスする
  2. @Routeの指定に従いコントローラーのメソッドを呼び出す
  3. メソッド内の処理が実行される
  4. @Templateに指定されたページを表示する

ちなみに先ほどソースコードも掲載したトップページに指定されているコントローラーには以下の1文しか記述がありませんでしたね。

    return [];

コントローラーのメソッドでreturnをすると@Templateに指定されたTwigファイルをもとに画面を表示しますが、この際コントローラーからTwigファイルにデータを渡すことができます。

渡すデータを戻り値として指定しますが、トップページの場合特に渡すデータがないため空の配列を返しているわけです。

あまり実践的ではない方法ですが、とりあえずトップページを表示するメソッドであるTopController.phpのindexメソッドをこのように書き換えてみましょう。

    /**
* @Route("/", name="homepage")
* @Template("index.twig")
*/
public function index()
{
echo "Hello";
return [];
}

こうするとトップページアクセスした時に「Hello」という文字列が表示されます。

本来表示を変更する場合twigファイルを変更しなければならないので、表示が崩れてしまいますね。

もうちょっとわかりやすい例を見る

さて、トップページはここまで説明した通りコントローラー内にこれといった処理が記述されておらずサンプルとしては適当ではありませんでした。

そこでもうちょっと処理が多いページを見てみましょう。

例えば会員登録ページです。

会員登録ページはsrc/Eccube/Controllerディレクトリの中のEntryController.phpが該当します。

ちなみにコントローラーの見つけ方は簡単です。

例えばEC-CUBEで構築したサイトから新規会員登録ページを開いてみてください。

URLが「https://○○○.com/entry」であることがわかると思います。

ということは、先ほど説明したアノテーションで@Route(“entry”と指定してあるメソッドを見つければ良いわけです。

EntryController.phpのなかでアノテーションで@Route(“entry”が指定されているindexメソッドをチェックしてみましょう。

全て貼り付けると長くなってしまうので、ざっくりと全体の処理の流れだけ解説します。

  1. ログイン済みの場合マイページにリダイレクトする
  2. 会員登録ページのフォーム情報を取得する
  3. フォームが入力済みでなければ新しいフォームを表示する
  4. フォーム入力済みでmodeがconfirmの場合にはEntry/confirm.twigを表示する
  5. フォーム入力済みでmodeがcompleteの場合には仮会員登録を行いメールを送信する
  6. 完了画面に遷移する

イベントの登録など省略した部分はありますが、大まかに説明すると以上のような流れで処理をしています。

@Templateには”Entry/index.twig”が指定されています。

先ほど同様、src/Eccube/Resource/template/defaultディレクトリ内のEntryディレクトリを開いてみましょう。

index.twigがありましたね。

こちらはトップページに比べるとなんとなくイメージがつきやすい内容になっていると思います。

入力フォームとしては一通りの種類を網羅しているので参考になるはずです。

なお、仮会員登録を行った後に送るメールには以下の処理で生成したURLが記載されています。

     $activateUrl = $this->generateUrl('entry_activate', ['secret_key' => $Customer->getSecretKey()], UrlGeneratorInterface::ABSOLUTE_URL);

このURLをクリックした際は、同じEntryController.phpのなかにあるactivateメソッドが呼び出されます。

activateメソッドのアノテーションを確認すると以下の記述が確認できます。

     @Route("/entry/activate/{secret_key}/{qtyInCart}", name="entry_activate")

{}で囲まれた値はパラメータで、今回の場合にはユーザー認証に使うランダムな文字列（secret_key）が指定されています。

activateの中で仮会員フラグの設定を更新し、本会員へ変更しています。

Customizeディレクトリでカスタマイズしてみる

さて、ここまでの説明でなんとなくの流れや動きのイメージができたと思います。

そこで実際にカスタマイズを行ってみましょう。

もちろんこれまで説明したコントローラーやTwigを直接修正しても構いませんが、冒頭で説明したような弊害があります。

そこで、今回はCustomizeディレクトリを使用したカスタマイズの手順を解説してみたいと思います。

先ほど例にとったEntryController.phpを修正してみましょう。

EntryController.phpのindexメソッドでは最終的に会員の仮登録を行い、完了画面に遷移します。

具体的には203行目付近のこの部分です。

        log_info('仮会員登録完了画面へリダイレクト');
return $this->redirectToRoute('entry_complete');

ログを出力してからentry_completeにリダイレクトしていることがわかります。

全くもって無意味ですが、これをトップページに遷移するように修正してみましょう。

ちなみに本体を直接カスタマイズする場合には、以下のように書き換えるだけです。

         return $this->redirectToRoute('homepage');

これをCustomizeディレクトリを利用して実装する場合の手順を解説します。

1.EntryController.phpをコピーする

Customizeディレクトリを利用したカスタマイズは、冒頭でも説明したように本体の処理を上書きするイメージです。

そのための第一歩として本体のソースコードをCustomizeディレクトリにコピーします。

今回はsrc/Eccube/Controller/EntryController.phpをカスタマイズしますから、これをコピーします。

貼り付け先はCustomizeディレクトリの中にあるControllerディレクトリ配下です。

具体的にはapp/Customize/ControllerにEntryController.phpをコピーします。

この時点でEC-CUBEのサイトにアクセスすると何も変化はありませんが、実際にはこれまでsrc/Eccube/Controller/EntryController.phpで行っていた処理がapp/Customize/Controller/EntryController.phpに置き換わっています。

2.修正する

続けてCustomizeディレクトリにコピーしたファイルを修正していきます。

まず始めに一番最初の行にあるnamespaceの宣言を修正します。

以下のようになっているものを、

namespace Eccube\Controller;

以下のように修正します。

namespace Customize\Controller;

あとは肝心の修正を行っていくだけです。

203行目付近のこの部分を

        return $this->redirectToRoute('entry_complete');

以下のように修正します。

         return $this->redirectToRoute('homepage');

これで会員登録（仮登録）を行うとトップページに遷移するようになりました。

3.不要なメソッドを削除する

さて、EntryController.phpにはindexメソッド以外にもcompleteメソッドやactivateメソッドなどいくつかのメソッドが定義されています。

これらは今回カスタマイズしませんでした。

そこで、indexメソッド以外のカスタマイズに不要なメソッドは削除してしまいましょう。

同じEntryControllerというクラス内のメソッドであっても、Customizeディレクトリ側に定義されていないメソッドは本体側のソースコードが参照されます。

つまり、Customizeディレクトリにコピーしてきたソースコードからカスタマイズ不要なメソッドは削除しておくべきということです。

まとめ

EC-CUBEをカスタマイズしたいけど情報が少ない！取っ掛かりが掴めない！

そんな方に向けてカスタマイズの小さな第一歩を踏み出せるように情報をまとめてみました。

まずはコントローラーの動きをなんとなく理解して、カスタマイズの手順を軽く知っておけば、後はソースコードを読み解きながらなんとか答えに辿り着けると思います。

今回はMVCのMやVに当たる部分にあまり触れませんでしたが、まずは基本のキということでCの部分を解説してみました。

タイトルとURLをコピーしました