EC-CUBE 3系は、PHPの軽量フレームワーク「Silex」(内部的にSymfony2系のコンポーネント群を利用)をベースに構築されたオープンソースのECサイト構築システムで、ソース本体を置くsrc、設定やログ・プラグインを置くapp、外部公開用のhtml、ライブラリ群のvendorという4つの主要ディレクトリを軸に構成されています。本記事では、この3系のディレクトリ構成と主要ファイルの役割を、本体・公開・設定の3つの観点から整理します。なお、より新しい4系では構成が変わっているため、対象バージョンの公式開発ドキュメントとあわせてご確認ください。

親カテゴリの解説は EC-CUBE3 を参照してください。

この記事の要点
EC-CUBE 3系はSilex(Symfony2系コンポーネント利用)をベースとし、2系から大きくディレクトリ構成が変わっている。 主要ディレクトリは src(本体)・app(設定/キャッシュ/ログ/プラグイン)・html(公開ディレクトリ)・vendor(ライブラリ)の4つ。 Webサーバーのドキュメントルートは html に向け、外部から直接参照させたくない src・app・vendor は公開領域の外に置くのが基本。 カスタマイズは src や vendor を直接書き換えず、プラグインやテンプレート・設定の上書きで行うのが原則。 設定ファイル類はインストール時に app/config 配下へ生成され、雛形(.dist)とは別管理になる。

EC-CUBE 3系の構成概要

EC-CUBE 3系は、それ以前の2系から設計が刷新されたバージョンです。マイクロフレームワークであるSilexを土台にしており、そのSilex自体がSymfony2系の各コンポーネント(ルーティング、フォーム、セキュリティ、設定など)を組み合わせて作られています。データベース操作にはORMであるDoctrineを、テンプレートエンジンにはTwigを採用しています。

そのため、ディレクトリ構成やソースコードの考え方はSymfony2系に近く、Symfonyの基本を押さえておくと全体像をつかみやすくなります。2系の構成をそのまま引きずらず、3系は「本体(src)」「環境依存(app)」「公開(html)」を明確に分離している点が大きな特徴です。

主要ディレクトリ一覧

インストール直後のトップ階層には、おおむね次のようなディレクトリが並びます。役割と「直接編集してよいか」の目安を以下にまとめます。

ディレクトリ	役割	主な中身	直接編集
src	EC-CUBEのコア(本体)ソース	src/Eccube 配下にPHPクラスやコア用テンプレート	原則しない
app	環境ごとに変わるものを配置	設定ファイル、キャッシュ、ログ、プラグイン、テンプレート	用途による
html	公開ディレクトリ(ドキュメントルート)	index.php、CSS/JS/画像などの公開リソース	リソースは可
vendor	外部ライブラリ群	Silex・Symfonyコンポーネント・Doctrine 等	しない

このうち、利用者が日常的に触れるのは主にappとhtmlで、srcとvendorは基本的に「読む対象」であって「書き換える対象」ではありません。

src(コア本体)

EC-CUBE本体のソースコードが収められたディレクトリで、実体の多くは src/Eccube 配下にあります。代表的なサブディレクトリは次のとおりです。

パス	役割
src/Eccube/Controller	各画面のコントローラ(リクエスト処理の入口)
src/Eccube/ControllerProvider	URLとコントローラを結びつけるルーティング定義
src/Eccube/Entity	データベースのテーブル・カラムに対応するエンティティ
src/Eccube/Repository	エンティティに対する検索・取得などのデータアクセス
src/Eccube/Form	入力フォームの定義(項目やバリデーション)
src/Eccube/Service	受注処理など業務ロジックを担うサービス層
src/Eccube/Resource	コア用のテンプレート(template)や設定(config)、翻訳(locale)など
src/Eccube/Common/Constant.php	バージョンなどの基本情報を持つ定数

このディレクトリを直接書き換えると、バージョンアップ時に変更が上書きされたり、不具合の原因になったりします。カスタマイズは後述のプラグインや上書きの仕組みで行うのが原則です。

app(設定・キャッシュ・ログ・プラグイン)

「主に環境によって変更が入るもの」を配置するディレクトリです。サーバーごとに異なる設定や、運用中に増えていくログ・キャッシュ、導入したプラグインなどが置かれます。

パス	役割
app/config	設定ファイルを配置(インストール時に生成)
app/cache	Twigテンプレートやコンテナなどのキャッシュ
app/log	ログファイル(フロント・管理画面のアクセス/エラー記録など)
app/Plugin	導入したプラグインの本体
app/template	フロント/管理/各プラグインのテンプレート上書き先

ログは日付ごとのファイルとして app/log 配下へ出力されるのが一般的で、不具合調査の起点になります。app/cache は書き込み権限が必要で、内容を消すとキャッシュは再生成されます。

html(公開ディレクトリ)

Webサーバーのドキュメントルートに相当し、ブラウザから直接参照される物だけを置くディレクトリです。アプリケーションへの入口となる html/index.php や、CSS・JavaScript・画像といった公開リソースが含まれます。アップロードされた商品画像などの保存先も、この公開領域の配下に用意されます。

セキュリティ上、src・app・vendor は html の外側(公開されない場所)に置き、ドキュメントルートを html に向けるのが基本構成です。これにより、設定ファイルやソース本体が直接URLで読まれることを防ぎます。

vendor(外部ライブラリ)

Composerで導入される外部ライブラリがまとまったディレクトリです。土台となるSilexやSymfony2系の各コンポーネント、Doctrine、Twigなどがここに入ります。手動編集はせず、構成の変更が必要な場合はComposer経由で管理します。

設定ファイルの位置づけ

3系では、データベース接続やメール、各種パスといった環境依存の設定が app/config 配下にまとめられます。これらの設定ファイルは、配布物に含まれる雛形(末尾が .dist のファイルなど)をもとに、インストール時に実ファイルが生成されるのが基本です。雛形そのものはバージョン管理されていても、生成後の実ファイルは環境ごとの値を持つため別管理になります。

典型的には、データベース接続情報・メール送信設定・サイトのパスやURLに関する設定などが、それぞれ個別のファイルとして app/config 配下に置かれます。具体的なファイル名や項目はバージョンによって異なるため、設定値を編集する際は、実際の環境の app/config 配下を確認するか、対象バージョンの公式ドキュメントを参照してください。

このほか、プログラム内部で使う定数は src/Eccube/Common/Constant.php や src/Eccube/Resource/config/constant.yml.dist といったコア側にも定義されています。これらは環境依存ではないため、編集対象はあくまで app/config 側と覚えておくと混乱しにくくなります。

カスタマイズの基本

3系のカスタマイズは「本体(src)・ライブラリ(vendor)を直接いじらない」が大原則です。代わりに、次のいずれかの方法を使います。

• プラグイン: 機能追加や処理の差し替えはプラグインとして実装し、app/Plugin 配下に配置する。イベント(フック)に処理を差し込むことで、本体コードを変えずに挙動を拡張できる。
• テンプレートの上書き: 画面の見た目を変えたい場合は、コア側のテンプレートを app/template 側へコピーして編集する。デザイン変更だけならこの方法で完結することが多い。
• 設定での切り替え: 環境依存の挙動は app/config 配下の設定で調整する。

コントローラやエンティティの挙動を理解する際は、本体側の src/Eccube/Controller などを「お手本(参照元)」として読み、同様の構造でプラグイン側に実装するのが定石です。読むのはコア、書くのはプラグイン・テンプレート・設定、という住み分けを意識すると安全に拡張できます。

公開ディレクトリ(html)の役割を再確認

html はブラウザからアクセスされる唯一の入口です。リクエストはまず html/index.php で受け取られ、そこから内部のアプリケーション(src 配下)へ処理が引き渡されます。つまり、URLとして外部に見えてよいのは html の中身だけであり、それ以外のディレクトリは公開しないという前提で構成されています。

サーバー移行や本番公開の際は、ドキュメントルートの指定が html を指しているかを必ず確認してください。ここを誤って一段上の階層に向けてしまうと、設定ファイルやソースが外部から読めてしまう重大なリスクにつながります。

落とし穴・注意点

本体(src)・vendorの直接改変: 数行の変更でもバージョンアップで上書きされ、保守不能になりやすい。原則プラグインやテンプレート上書きで対応する。 キャッシュの取り扱い: 変更が反映されない時は app/cache が古いことが多い。キャッシュ削除や再生成、ファイルの書き込み権限を確認する。 ドキュメントルートの設定ミス: html 以外を公開してしまうと、設定ファイルやソースが外部から参照され得る。公開対象は html のみに限定する。 2系の知識をそのまま流用: 3系はSilex/Symfony2系ベースで構成が大きく異なる。2系のディレクトリ感覚で探すと目的のファイルが見つからない。 4系との混同: 4系はさらに構成が変わっている。手元のバージョンを確認し、対象バージョンのドキュメントを参照する。 設定ファイルの場所の取り違え: 環境依存の編集は app/config 側。コア側の定数(src/Eccube 配下)を書き換えないよう注意する。

よくある質問

Q1. 小さな変更でもプラグインを作る必要がありますか。
A. 表示(デザイン)だけの変更であれば、テンプレートを app/template 側へコピーして編集するだけで済むことが多いです。一方、処理の流れや業務ロジックを変える場合は、本体を直接書き換えず、プラグインとして実装するのが安全です。本体を直接編集するとバージョンアップ時に失われ、保守が困難になります。

Q2. データベースの接続情報はどこで変更しますか。
A. 環境依存の設定は app/config 配下に置かれる設定ファイルで管理されます。これらはインストール時に雛形から生成されるため、編集対象は実際の環境の app/config 配下になります。具体的なファイル名や項目名はバージョンで異なるため、対象バージョンの公式ドキュメントとあわせて確認してください。

Q3. 変更したのに画面に反映されません。原因は何が考えられますか。
A. まず app/cache のキャッシュが古い可能性を疑ってください。キャッシュの削除・再生成で解決することが多くあります。あわせて app/cache・app/log の書き込み権限、編集したファイルの配置場所(コア側を見て app 側を編集できているか)、ブラウザ側のキャッシュも確認するとよいでしょう。

本記事は3系の一般的な構成を整理したものです。実際のファイル名・パス・設定項目はバージョンや環境によって差異があるため、運用前には必ず対象バージョンの公式開発ドキュメントと実機の構成を照合してください。