【EC-CUBE 4】カスタマイズのまとめ

2026年8月14日

EC-CUBE 4 のカスタマイズ方法をまとめた索引ページです。管理画面の操作だけでできることから、ファイルサーバーやデータベースを触る本格的なカスタマイズまで、難易度の低い順に並べています。筆者が実際に手を動かした内容を随時追加しています。

EC-CUBEのカスタマイズは、何から手をつければいい？

カスタマイズは大きく2段階に分かれます。

1段階目は管理画面の操作だけで済むものです。「CSS管理」「JavaScript管理」やページ編集から、見た目や文言を変えられます。ファイルを触らないので失敗しても戻しやすく、ここから始めるのが安全です。

2段階目はファイルサーバーとデータベースを触るものです。独自ページの追加や商品情報の拡張ができますが、こちらへ進むなら最初にやるのはデバッグモードの設定です。初期状態ではエラーが起きても専用ページが出るだけで原因が分からず、ここでつまずく人がとても多いためです。

下の「学習の順路」に、実際に手を動かす順番でまとめました。

EC-CUBEとは？

ネットショップの製作や管理ができるオープンソース型ソフトウェアです。誰でも無料でインストールでき、サイトの外観からカート機能、売上管理といった基本的な機能が備わっています。ドトールのオンラインショップなど、35,000を超える店舗で運用されています（公式サイト「当社調べ」）。詳細は EC-CUBE公式サイトをご確認ください。

EC-CUBEは誰でも無料で使え、かつカスタマイズ性が高いのが特徴です。が、初心者にはそのカスタマイズがなかなか難しい。

サイト内の文章や配置を少し変更する程度ならあまり問題ありませんが、

商品の管理項目を増やし、それをデータベースに保存する
データベースから特定の商品や顧客情報を抽出する

といった機能は、サーバーやデータベースの管理技術、プログラミング技術などが必要となります。

本サイトでは、筆者自身が実際に行ったカスタマイズ方法を備忘録としてまとめ、できる限り分かりやすく公開しています。ただし独学のため、中には非効率な方法だったり、バージョンや動作環境によって機能しなかったりなどあるかもしれません。その点はご容赦ください。

学習の順路｜どの記事から読むか

記事数が多いので、はじめての方向けに手を動かす順番を並べました。この7ステップを終えると、独自ページを作ってデータベースの情報を表示するところまで到達できます。

順	やること	読む記事
1	テンプレートの読み方を覚える	Twig まとめ(1) 継承やブロック
2	見た目を変えてみる	CSSの簡単設定と反映方法
3	エラーを読めるようにする	デバッグモードの設定/解除方法
4	変数の中身を見る	変数の中身を確認する方法（dump関数）
5	自前のページを作る	新規ページの作成方法（user_dataなし）
6	データベースから商品を取り出す	データベースから特定のデータを抽出して表示する
7	データベースを拡張する	既存テーブルに新しいフィールドを追加する

まだEC-CUBEを入れていない方へ。XServer限定ですが、インストール手順とテスト環境の作り方をまとめています。運用中のサイトをいきなり触るのが不安な場合は、先にテスト環境を用意するのがおすすめです。

本記事の内容は EC-CUBE 4.2.1 〜 4.3.0、サーバーは XServer で確認したものです。
2026年8月時点の最新版は 4.3.1-p1（2026年3月4日リリース）です。バージョンによって画面やファイル構成が異なる場合があります。

管理画面の操作のみでできるカスタマイズ

コンテンツ管理から、既存ページの編集や新規ページの作成ができます。

ここで作成した新規ページには user_data というURLが自動で入ってしまい、データベースの情報を取得したり更新したりといったことが基本的にできません。したがって、そのページのみで完結する内容（例えばブログ）が中心となります。より柔軟なページを作成したい場合は、ファイルサーバーにControllerファイルをアップするなど、少し高度なカスタマイズが必要です。詳細は新規ページ作成のセクションで解説しています。

またページのレイアウトや装飾などをがっつり修正したいなら、HTMLやCSS、JavaScriptの知識に加えて、Twigと呼ばれるPHP向けのテンプレートエンジンの知識が必要です。

Twigテンプレートを使いこなそう！

通常のHTMLとは異なった記法となるTwigテンプレートについてまとめています。

既存のTwigテンプレートを修正することで、以下のようなカスタマイズが行えます。

CSSとJavaScriptを使ってデザインやアクションを変更しよう！

CSSについて。EC-CUBE管理ページから「CSS管理」を開いてCSSコードを書き込むと、その内容がサイト全体に反映されます。また「CSS管理」ではなく各ページに直接コードを記載することで、そのページのみに適用させることもできます。

JavaScriptについて。「JavaScript管理」を開いてJavaScriptコードを書き込むと、その内容がサイト全体に反映されます。こちらも各ページに直接コードを記載すれば、そのページのみに適用できます。

HTML / CSS / JavaScript については、以下の記事に色々な実装パターン（メッセージ表示、画像拡大、各種UIなど）を公開しています。EC-CUBE関連記事と合わせて参考にしていただければと思います。

ファイルサーバーやデータベースの操作が必要なカスタマイズ

本格的にカスタマイズするなら、やはりファイルサーバーやデータベース操作はできるようにしておきたいところ。難易度は高いですが、よりオリジナリティの高いECサイトが作れます。

操作を誤ると、取り返しのつかない事態に発展する可能性があります（当方では責任を負いかねますので、自己責任でお願いします）。バックアップを用意しておくか、慣れるまでは練習用の模擬サイトを用意して試行錯誤してみるのをおすすめします。

なお、EC-CUBEにはSymfonyと呼ばれるPHPフレームワークが採用されています。

Symfonyとは？

PHP（プログラミング言語）で使うフレームワークです。これを利用することで、WebサイトやWebアプリを作るための時間と労力を大幅に節約できます。Symfonyが提供する部品（コンポーネント）を組み合わせることで、プログラムが作れます。それぞれの部品は特定の機能を持っており、データベースから情報を取得したり、ユーザーの入力を処理したりできます。

また、Symfonyは MVC（Model-View-Controller）という設計方法に基づいています。これはプログラムのコードを次の3つに分ける方法で、コードが整理されていて理解しやすくなります。

データの管理（Model）
表示の管理（View）
ユーザーからの命令の受け取り（Controller）

まずはデバッグモードを設定しよう

EC-CUBEの初期設定では、バグが発生しても専用のエラーページが表示されるようになっています。このページだけではエラー内容が全くわからないのですが、あらかじめデバッグモードを設定しておくことで、エラーの詳細が表示されるようになります。

デバッグモードの設定/解除方法

運用環境のときは、デバッグモードの解除を忘れないようにしてください。エラーの詳細にはファイルパスなどの内部情報が含まれるため、公開したままにするとセキュリティ上のリスクになります。

エラー別対処法

筆者が実際に遭遇したエラーへの対処法をまとめました。エラーメッセージから逆引きできる早見表を用意しているので、同じエラーに引っかかった際の参考にどうぞ。

遭遇したエラー＆対処法まとめ

デバッグに必須機能・dump()関数

EC-CUBEでは、デフォルトの状態でも数多くの変数が使われています。これらの変数の中身を表示するための関数が dump() です。

カスタマイズ時はもちろん、EC-CUBEのシステムを理解するのにも必須となる関数ですね。

変数の中身を確認する方法（dump関数）

dump() 関数はデバッグモードを設定しているときにしか使えません。通常の運用環境ではエラーが出ます。

設定値と共通処理の整理

カスタマイズが増えてくると、コード内に直接書いた数値や文字列があちこちに散らばってきます。設定値は定数としてまとめ、複数の画面から呼ぶ処理は Service に切り出しておくと、後から直すのが楽になります。

ページの基本設定（headタグの編集）に関するカスタマイズ

default_frame.twig というファイルを編集することで、サイトのタイトルやアイコン（ファビコン）などの編集ができます。該当ファイルを修正してアップするだけで手数が少なく、初心者でも比較的簡単にできるカスタマイズです。

新規ページ作成（Controllerの編集）に関するカスタマイズ

新規ページの作成はEC-CUBEの管理画面からでもできますが、先述のとおり user_data というURLが自動で入ってしまったり、データベースから情報を取得したりといったことができません。

こちらの方法を用いることで、URLを自由に決めることはもちろん、データベースから特定の情報を選んで表示させるといったことができるようになります。

こういった新規ページの作成には、Controllerと呼ばれるファイルの作成が必須となります。まずは比較的簡単なところからで、新規ページのURLから user_data を消すと同時に簡単なControllerファイルを作成できる、以下の記事がおすすめです。

新規ページを作成できたら、Controller経由で実際にデータを渡してWebページに表示させてみましょう。

（初心者向け）Controllerを使って表示ページにデータを渡す方法

さらに、データベースから情報を引っ張ってきて表示させてみましょう。ここで登場する Repository は、データベースからレコードを取り出す窓口の役割を持つクラスです。

このあたりの記事で、データベースの情報取得＆Webページへの表示方法が何となくでも理解できるようになれば嬉しいです。

（応用）タグ別や新着順など、特定の商品をピックアップして一覧表示する

データベースをより複雑な条件で検索したい場合は、以下の記事で紹介しています。

このあたりを使いこなせば、以下のようなページを作ることもできます。ここまでできれば、かなり実用的なカスタマイズになるかと思います。

（応用）特定の商品を非表示にする

商品の公開ステータスを利用して、特定の商品を非表示にする仕組みを解説しています。前項のようなオリジナル商品一覧ページを作成した場合に、合わせて実装しておくとベターです。

公開状態に応じて商品を非表示にする方法

（応用）ID別に詳細ページを作成できる自動フェッチ

ID別に複数ページを用意する場合は「自動フェッチ」機能が便利です。商品詳細ページ (ドメイン名)/products/detail/1 のように、URLの末尾に指定した数字と同じIDをもつデータ（レコード）を抽出し、表示できます。

ID毎に詳細情報を表示するページの作り方（自動フェッチ）

（応用）商品一覧ページを分割表示する（ページネーション）

商品の数が多い場合、複数ページにまたがって表示させるページネーションと呼ばれる機能も実装できます。デフォルトで用意されている商品一覧（カテゴリー別商品一覧）ページにも実装されており、こちらに新しい並び替えオプションを追加する場合と、独自に作成した商品一覧ページに実装する場合の2パターンあります。

データベース拡張や変更に関するカスタマイズ

既存のテーブル（商品情報や会員情報）に新しい項目（属性）を追加したいときや、新規でオリジナルのテーブルを追加したい場合はこちら。

EC-CUBEのデータベース拡張は少し癖があり、サーバーにSSH接続してコマンド入力する必要があります。筆者は初めてのトライでかなり苦戦しましたので、なるべく手順を詳細に書いたつもりです。

やりたいこと	記事
既存のテーブルを編集する	既存テーブルに新しいフィールド（カラム）を追加するカスタマイズ
新規にテーブルを作成する（dtbから始まる通常のテーブル）	新規テーブルをデータベースに追加するカスタマイズ
新規にテーブルを作成する（mtbから始まるマスターテーブル）	マスターテーブルを新規に作成し、管理画面で操作する方法
作成したテーブルを修正する	作成済テーブルを修正する方法
【発展】テーブル同士を連携させる	複数のテーブル同士を連携（リレーション）するカスタマイズ既存テーブルと新規テーブルを連携（リレーション）するカスタマイズ
【発展】CSVに新規項目を追加する	CSV出力／登録に新規項目を追加するカスタマイズ
【発展】値をまとめて書き換える	SQLでテーブルの値を一括変更する

データベースアクセスの基本操作（レコードの作成・取得・更新・削除）

データベースの活用に関わる基本的な処理は、以下の頭文字をとって CRUD と呼ばれます。

頭文字	処理
`Create`	レコードの作成
`Read`	レコードの取得
`Update`	レコードの更新
`Delete`	レコードの削除

このうち取得については、前項の新規ページ作成（Controllerの修正）で少し紹介しました。ただテーブルを独自に作成した場合、そのテーブルからレコードを取り出すためのRepositoryも自身で用意する必要があります。

以下の記事で、簡単なRepositoryを作成する方法と、それを使ってレコードを取り出す方法を解説しています。

レコードの抽出方法についてはデータベースから情報を取得する項でも紹介していますので、合わせてご覧ください。

残る3つの処理についてはRepositoryではなく、Manager（マネージャ）というクラスを利用します。基本的な使い方は以下の記事でそれぞれ解説しています。

処理	記事
レコードの追加 `Create`	オリジナルテーブルに新規データ（レコード）を追加する方法
レコードの更新 `Update`	オリジナルテーブルの保存データ（レコード）を更新する方法ゲスト購入に会員情報を後から紐づける方法
レコードの削除 `Delete`	オリジナルテーブルの保存データ（レコード）を削除する方法

レコードの追加については、以下で紹介する FormType を使う方法が一般的です。
管理画面に新しくメニューを追加し、レコードの追加・更新・削除を行う方法も後述しています。

フォーム（お問い合わせ/会員登録/注文画面/商品登録など）に関するカスタマイズ

お問い合わせや会員登録、管理画面の商品登録など、ユーザーが特定のデータを入力して送信する「フォーム」をカスタマイズしたい場合はこちら。

FormType / FormExtension を使ってフォームを拡張する

フォーム生成はControllerでも行えますが、一般には FormType というファイルを使って行います。

FormTypeを使ってフォームを生成する方法

一方、お問い合わせフォームや商品登録など、デフォルトで用意されたフォームを拡張する場合は FormExtension を使います。

拡張したいフォーム	記事
お問い合わせフォームに新規項目を追加する	お問い合わせフォームに新しい項目を追加する方法（FormExtensionを使ったFormTypeのカスタマイズ）お問い合わせフォームに新しい項目を追加するカスタマイズ
注文画面に新規項目を追加する	注文内容に新しい項目を追加し、注文画面をカスタマイズしてみた
管理画面の商品登録に新規項目を追加する	商品登録にオリジナルの新規項目を追加するカスタマイズ

テキスト入力以外のフォームを実装する

テキスト以外にも、普段よく目にする様々な入力フォームを実装できます。

入力にルールを設定する

フォームには、入力を必須にしたり入力文字数を制限したりといったルール（バリデーション）も設定できます。

メールに関するカスタマイズ

メールテンプレートを追加したり、自動送信メールを変更したりするカスタマイズ方法についてまとめています。

管理画面のカスタマイズ

管理画面に新しいメニューを追加して、データを追加・更新・削除できるようにするカスタマイズです。

Controller、Repository、FormType、Entity、Twigなど、EC-CUBEの構造が一通り理解できていないと難しいかもしれません。上の各セクションをひととおり読んでから取りかかるのがおすすめです。

そのほか、管理画面まわりでは以下のカスタマイズも紹介しています。

【実践】価格帯から商品を検索できるブロックの作成

独自のリポジトリとフォームタイプを作成し、新規ページに商品一覧を表示させる実践編です。

価格帯から商品を検索できるブロックを作ってみた

【実践】よくある質問ページの作成

新規ページの作成からデータベースの拡張、管理画面のカスタマイズまでを応用した実践編です。

運用・トラブル対応

カスタマイズそのものではありませんが、EC-CUBEを運用していると避けて通れない設定やトラブルへの対処法です。困ったときの逆引きにどうぞ。

困りごと	記事
管理画面にログインできない	管理画面のログインIDとパスワードが分からないときの対処法
管理画面のURLを変えたい	管理画面のURLを変更する方法
ショップからのメールが届かない	ショップメールがGmailなどで受信できない問題について
アクセス解析を入れたい	Google Analytics 4の設定方法
PHPのバージョンを変えたい	【XServer】PHPのバージョン切り替え方法（コマンドライン）
URLを1つに統一したい	wwwやindex.phpを含むURLから含まないURLへ自動転送する

まとめ

EC-CUBE 4のカスタマイズ記事をまとめました。どこから読めばいいか迷ったら、冒頭の「学習の順路」の7ステップから始めてみてください。

あらためて、大きな流れは次のとおりです。

管理画面の「CSS管理」「JavaScript管理」とTwigの編集で、見た目を変えられるようになる
デバッグモードと dump() で、エラーと変数の中身を読めるようになる
Controllerで独自ページを作り、Repositoryでデータベースから情報を取り出せるようになる
テーブルを拡張し、フォームや管理画面から自前のデータを扱えるようになる

冒頭のとおり、筆者自身も勉強＆実践中です。引き続き、自身の備忘録の意味合いも込めて、カスタマイズ方法を随時更新していきます。

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！