2026年09月16日

EC-CUBE4系を触ってみた（その1：ローカル環境構築〜会員機能カスタマイズ）

システム開発, PHP, Docker

はじめに

近年、オンラインショップの需要が急速に高まっており、多くの企業や個人がECサイトを運営するようになっています。その中で、日本発のオープンソースECプラットフォーム「EC-CUBE」は、高いカスタマイズ性と柔軟性を備え、多くのユーザーに支持されています。

本記事では、EC-CUBEの基本的な使い方をわかりやすく解説し、初心者でもスムーズにECサイトを立ち上げられるようにサポートします。インストール方法から基本設定、運用のポイントまで順を追って紹介しますので、ぜひ最後までお読みください。

参考資料

EC-CUBE4.3ダウンロード

EC-CUBE 4.3

作業環境

Apache 2.4.x
MySQL 8.x
PHP 8.1.x

ディレクトリ構成

ディレクトリ・ファイル構成

EC-CUBEの起動

公式サイトからパッケージ版をダウンロードして、ローカルに配置する。

EC-CUBE/
├── app/                 アプリケーション固有の設定やカスタマイズコードを配置
│   ├── Customize        カスタマイズ用のPHPコードを配置
│   ├── Plugin           インストールされたプラグインを配置
│   ├── PluginData       プラグインが利用するファイルを配置
│   ├── config           各種設定ファイルを配置
│   ├── proxy            Entity拡張で生成されたProxyクラスを配置
│   └── template         上書きされたテンプレート（Twig）を配置
├── bin/                 コンソール操作など開発用コマンドを配置（例：bin/console）
├── html/                公開ディレクトリ（js, css, 画像などのリソースを配置）
├── src/                 EC-CUBE本体のPHP・Twigファイルを配置
├── tests/               自動テストコードを配置
├── var/                 キャッシュ・ログなど実行時に生成されるファイルを配置
└── vendor/              Composerで管理された外部ライブラリを配置

ターミナルを開き、EC-CUBEのルートディレクトリに移動

cd EC-CUBE

Dockerコンテナを立ち上げる

docker-compose up -d

Dockerコンテナ起動後のターミナル出力

ここまで立ち上がったのは、EC-CUBEのアプリケーションサーバ及びメールサーバ

127.0.0.1:8080 => EC-CUBEトップページ
127.0.0.1:8080/admin/login => EC-CUBE管理画面(admin,password)
127.0.0.1:1080 => MailCatcherクライアントページ

MySQLへの接続

初期起動時、EC-CUBEはSQLiteを使い、データを管理している。本番環境の際に、SQLiteを使わないケースが多いため、docker-compose.ymlを修正し、MySQLに切り替え作業を行う。

# MySQLコンテナを立ち上げる

mysql:
  image: mysql:8.4
  container_name: mysql_db
  environment:
    MYSQL_ROOT_PASSWORD: root
    MYSQL_DATABASE: eccube4
    MYSQL_USER: docker
    MYSQL_PASSWORD: docker
    TZ: 'Asia/Tokyo'
  command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
  volumes:
    - ./mysql/data:/var/lib/mysql
    - ./mysql/my.cnf:/etc/mysql/conf.d/my.cnf
    - ./mysql/sql:/docker-entrypoint-initdb.d
  ports:
    - 13306:3306
  networks:
    - backend

# EC-CUBEコンテナに追加

DATABASE_URL: "mysql://docker:docker@mysql_db:3306/eccube4"
depends_on:
  - mysql

docker-compose up -dを実行、データベース及びテーブルは自動的に作成される

MySQLに切り替え後、テーブルが自動作成された画面

環境変数の管理

envファイルについては、公式ドキュメントから開発用途での環境変数を設定するためのものであり、本番環境での使用は推奨されていないため、ローカル開発の時の管理方法だけ説明します。

docker起動時直接環境変数設定の場合、コンテナのenvironmentで管理している。docker起動時自動的にセットされる

docker-compose.ymlのenvironmentで環境変数を設定している画面

envファイルで環境変数を管理するサーバ

システム起動時、以下のロジックで環境変数を検索している

　　サーバ環境変数 > .env > .env.install

if (!isset($_SERVER['APP_ENV'])) {
    if (!class_exists(Dotenv::class)) {
        throw new \RuntimeException('APP_ENV environment variable is not defined. You need to define environment variables for configuration or add "symfony/dotenv" as a Composer dependency to load variables from a .env file.');
    }

    if (file_exists(__DIR__.'/.env')) {
        (Dotenv::createUnsafeMutable(__DIR__))->load();

        if (strpos(getenv('DATABASE_URL'), 'sqlite') !== false && !extension_loaded('pdo_sqlite')) {
            (Dotenv::createUnsafeMutable(__DIR__, '.env.install'))->load();
        }
    } else {
        (Dotenv::createUnsafeMutable(__DIR__, '.env.install'))->load();
    }
}

　以下のようにファイルを作成すれば、dockerで起動時直接環境変数設定と同じことができる。

###> symfony/framework-bundle ###
APP_ENV=install
APP_DEBUG=1
DATABASE_URL=mysql://docker:docker@mysql_db:3306/eccube4
DATABASE_SERVER_VERSION=3
DATABASE_CHARSET=utf8
MAILER_DSN=smtp://mailcatcher:1025
ECCUBE_AUTH_MAGIC=<change.me>
###< symfony/framework-bundle ###

会員登録機能カスタマイズ

目標：既存会員登録機能に、趣味を追加する

①カスタマイズコントローラーを作成する

src/Eccube/Controller/EntryController.php -> app/Customize/Controller/EntryController.phpにコピー

コピーしたあと、ネームスペースとクラスのインポートを修正してください

②アプリケーションサーバに入り、キャッシュクリアして新たなコントローラーを反映させる

# コンテナに入るコマンド
docker exec -it ec-cube-ec-cube-1 bash
# キャッシュクリア用コマンド
bin/console cache:clear

③データベースにカラムを追加

app/Customize/Entity/CustomerTrait.phpを以下のように作成する

<?php

namespace Customize\Entity;

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

/**
 * @EntityExtension("Eccube\Entity\Customer")
 */
trait CustomerTrait
{
    /**
     * @ORM\Column(type="string", nullable=true)
     */
    public $hobby;
}

順番にコマンドを実行する

## Proxyクラスを生成します。
bin/console eccube:generate:proxies
## 作成した Proxy クラスを確実に認識できるようキャッシュを削除
bin/console cache:clear --no-warmup
## 実行する SQL を確認
bin/console doctrine:schema:update --dump-sql
## SQL を実行
bin/console doctrine:schema:update --dump-sql --force

データベースにアクセスして確認すると、hobbyという新たなカラムがcustomerテーブルに追加された。

④新規登録画面のテンプレートを編集する

app/template/default/Entry/index.twig に以下のコードを追加する

<dl>
  <dt>
    {{ form_label(form.hobby, '趣味', { 'label_attr': {'class': 'ec-label' }}) }}
  </dt>
  <dd>
    <div class="ec-select{{ has_errors(form.hobby) ? ' error' }}">
      {{ form_widget(form.hobby) }}
      {{ form_errors(form.hobby) }}
    </div>
  </dd>
</dl>

EntryType.php本体は直接編集せず、app/Customize/Form/Type/Front/EntryTypeExtension.phpを新規作成して以下の内容を追加する

<?php
namespace Customize\Form\Type\Front;
use Eccube\Form\Type\Front\EntryType;
use Symfony\Component\Form\AbstractTypeExtension;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
class EntryTypeExtension extends AbstractTypeExtension
{
    public static function getExtendedTypes(): iterable
    {
        return [EntryType::class];
    }
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder->add('hobby', TextType::class, [
            'required' => false,
        ]);
    }
}

画面更新したら、趣味の入力欄が追加される
会員登録画面に追加された趣味の入力欄 ⑤確認画面のテンプレートを修正する app/template/default/Entry/confirm.twig に以下のコードを追加

<dl>
    <dt>
        {{ form_label(form.hobby, '趣味', {'label_attr': {'class': 'ec-label'}}) }}
    </dt>
    <dd>{{ form.hobby.vars.data }}
        {{ form_widget(form.hobby, { type: 'hidden'}) }}
    </dd>
</dl>

会員登録確認画面に表示された趣味の入力内容