【EC-CUBE 4】CSV出力／登録に新規項目を追加するカスタマイズ

2025年4月16日

EC-CUBE 4には、商品データをCSVで出力したり、CSVファイルをアップロードして一括で修正・登録できる便利な機能があります。しかし、標準では用意されていない独自の項目（たとえば「生産地」「JANコード」「ブランド名」など）をCSVで扱いたい場合、少しカスタマイズが必要になります。

そこで本記事では、以下のように「生産地（production_area）」という新しい項目を追加し、CSVからの読み込み・保存ができるようにする具体的なカスタマイズ手順をご紹介します。

商品テーブル（dtb_product）に新規項目が追加されている状態からのカスタマイズです。既存のテーブルに項目を追加する方法については、以下記事を参考にしてください。

【EC-CUBE 4】商品登録にオリジナルの新規項目を追加するカスタマイズ

開発前にデバッグモードの設定をお薦めします

デバッグモードを設定しておくと、エラーが起きたときに詳細情報が表示されるようになります。
エラー箇所を探しやすくなるので、開発前に設定しておくのをオススメします。
デバッグモードの設定方法については以下記事で解説しています。

【EC-CUBE 4】デバッグモードの設定/解除方法

カスタマイズ後は、デバッグモードの解除を忘れないように。

【動作環境】
EC CUBEのバージョン：4.3.0
サーバー：XServer

カスタマイズの全体の流れ

「dtb_csv」テーブルに新規項目（本記事ではproduction_area）を追加する
「src/Eccube/Controller/Admin/Product/CsvImportController.php」を「app/Customize/Controller/Admin/Product」ディレクトリにコピー・追記する
「app/Customize/Resource/locale/messages.ja.yaml」にキーを追加する

STEP

dtb_csv テーブルに新規項目（production_area）を追加する

商品CSV登録では、EC-CUBEの「dtb_csv」テーブルの設定に従ってカラムが構成されます。そのため、新たな項目を追加するには、このテーブルにレコードを挿入する必要があります。

今回は、phpMyAdminを利用して以下のようにproduction_areaを追加しました。

csv_type_id	1 – 商品CSV
entity_name	Eccube\Entity\Product
field_name	production_area
disp_name	生産地
sort_no	10
enabled	1
discriminator_type	csv

追加したレコードの値

STEP

CsvImportController.php を Customize ディレクトリにコピー・追記する

元の CsvImportController（src/Eccube/Controller/Admin/Product/CsvImportController.php）を「app/Customize/Controller/Admin/Product」へコピーし、商品登録処理中にproduction_areaをセットする処理を追加します。

まずnamespaceを以下の通り修正します。

namespace Customize\Controller\Admin\Product;

続いて、csvProduct()メソッドに以下コードを追記します。

if (isset($row[$headerByKey['production_area']])) {
    if (StringUtil::isNotBlank($row[$headerByKey['production_area']])) {
        $Product->setProductionArea(StringUtil::trimAll($row[$headerByKey['production_area']]));
    } else {
        $Product->setProductionArea(null);
    }
}

最後に、getProductCsvHeader()メソッドに以下コードを追記します。

trans('admin.product.product_csv.production_area_col') => [
    'id' => 'production_area',
    'description' => 'admin.product.product_csv.production_area_description',
    'required' => false,
],

STEP

messages.ja.yaml にキーを追加する

翻訳ファイルにラベルと説明文を追加します。
admin.product.product_csv.production_area_descriptionに値をセットすると、その内容がCSVファイルフォーマットの説明テーブルに表示されるようになります。

admin.product.product_csv.production_area_col: 生産地
admin.product.product_csv.production_area_description: ''

STEP

キャッシュを削除

以上でカスタマイズ完了です。
キャッシュを削除してから、想定通りの動作をするか確認しましょう。

追加項目が他テーブルと連携（リレーション）している場合

production_area のような単純な値であれば、CSVからそのままセットできますが、他テーブルとリレーションしている項目（例：以下記事で追加したmaker など ManyToOne 関係にあるもの）を扱う場合は、同じ方法では処理が途中で止まってしまうことがあります。

カスタマイズ変更箇所：dtb_csv

「dtb_csv」にレコードを追加する際、reference_field_nameに連携先テーブルの参照したいカラム名を入力します。今回は「dtb_maker」のidを参照したいので、idと入力しました。

STEP

カスタマイズ変更箇所：CsvImportController.php

インポートしたCSVの値をセットする際は、idなどの単純な値ではなく、Makerエンティティの値をセットする必要があります。今回はCSVにメーカーのidをセットするので、このidとMakerRepositoryを使ってMakerエンティティの情報を取得し、その値をセットします。

// MakerRepository を利用するための準備
use Customize\Repository\MakerRepository;

/**
 * @var MakerRepository
 */
private $makerRepository;

public function __construct(
    MakerRepository $makerRepository,
    ...
) {
    $this->makerRepository = $makerRepository;
    ...
}

リポジトリを利用する準備ができたら、以下のようにMakerRepositoryを使ってエンティティを取得、セットします。

// 「maker」列がCSVに含まれている場合
if (isset($row[$headerByKey['maker']])) {

    // 全角・半角スペースを除去したIDを取得
    $makerId = StringUtil::trimAll($row[$headerByKey['maker']]);

    // IDが空でなく、数値であれば
    if (StringUtil::isNotBlank($makerId) && preg_match('/^\d+$/', $makerId)) {

        // idから Maker エンティティを取得
        $Maker = $this->makerRepository->find($makerId);

        // 見つかればセット、なければnullをセット（エラー抑制）
        $Product->setMaker($Maker ?: null);

    } else {
        // 数値でなければnullをセット
        $Product->setMaker(null);
    }
}

まとめ

EC-CUBE 4で商品CSV出力／登録機能に新しい項目を追加するには、

dtb_csv テーブルに追加したい項目のレコードを登録する
CSVコントローラーで処理を追記する
ヘッダー項目と翻訳キーを整える

というステップで対応できます。

CSVは商品管理やデータの一括更新にも欠かせない機能で、運用効率も大きく向上します。この方法は商品データ以外（会員、カテゴリなど）のCSVにも応用可能なので、ぜひ試してみてください！