商品CSV Pro プラグイン
数千〜数万件の大規模商品登録でも「504 Gateway Timeout」や「メモリ枯渇 (Out of Memory)」を起こさない次世代CSVインポートソリューション。ドライラン事前検証、URL画像並列自動保存、ZIP画像一括解凍、エラー行CSV即時ダウンロード機能を標準搭載しています。
1. プラグイン概要と主な機能
『商品CSV Pro プラグイン (AdvancedCsvPro)』は、標準のEC-CUBE商品CSV登録が抱える「途中でサーバーがタイムアウトする」「失敗した原因行が特定できない」「画像のアップロードが面倒」という運用課題を完全解決するために開発されたエンタープライズ対応プラグインです。
ドライラン（安全な事前検証）
DBを一切汚さずにCSVを事前全行スキャン。SKU重複やカテゴリ不整合、フォーマットエラーを事前に100%洗い出します。
AJAX分割処理 (Chunking Loop)
CSVを20〜100行ごとの小ブロックに自動分割し非同期実行。プログレスバーでリアルタイム進捗を表示しTimeoutを防止。
URL画像並列自動ダウンロード
CSV内の画像URL（https://...）からcURL Multiで並列一括ダウンロード。FTPや事前配置の手間をゼロにします。
画像ZIPファイル同時展開
CSVと一緒に画像ZIPをアップロードするだけで、サーバー上で瞬時に解凍して商品へ自動マッピングします。
エラー行のみのCSV再出力
エラーが発生した行だけを抽出し、末尾に「具体的なエラー理由」を追記したCSVを1クリックで出力・修正できます。
履歴管理 & ページネーション
過去のインポートログ、実行モード、成功/失敗件数を管理。不要になった一時ファイルやログの一括削除も可能です。
2. インストール・有効化手順
1. 管理画面からのインストール
EC-CUBE管理画面 設定 ＞ システム設定 ＞ プラグイン一覧 を開き、「新規追加」ボタンから AdvancedCsvPro.tar.gz をアップロードします。
一覧に追加された「商品CSV Pro」の右側にある「有効化」をクリックします。
左側ナビゲーションの 商品管理 ＞ 商品CSV Pro が追加されていることを確認します。
2. CLI（コンソールコマンド）からのインストール
# プラグインのインストールと有効化
$ bin/console eccube:plugin:install --code=AdvancedCsvPro --enable
# キャッシュのクリア
$ bin/console cache:clear --no-warmup3. CSVフォーマット・登録項目仕様
プラグイン管理画面の右上にある「フォーマットCSVダウンロード」ボタンから、いつでも最新の標準テンプレートCSV（UTF-8 BOM付き）を取得できます。
| CSVヘッダー名 | 必須 / 任意 | 設定値の説明・記入例 |
|---|---|---|
| 商品ID | 任意 | 既存商品の更新時は必須。新規登録時は空欄のままにします。 |
| 公開ステータス(ID) | 必須 | 1（公開）、2（非公開）、3（廃止）のいずれかを半角数値で入力。 |
| 商品名 | 必須 | 商品の名称（例: オーガニックコットンTシャツ）。 |
| ショップ用メモ | 任意 | 管理者用メモ（フロントには表示されません）。 |
| 商品説明(一覧) | 任意 | 商品一覧ページで表示される簡易説明文。 |
| 商品説明(詳細) | 任意 | 商品詳細ページの説明文（HTMLタグ使用可能）。 |
| 検索ワード | 任意 | カンマ区切りで複数検索キーワードを設定（例: トップス,半袖,夏服）。 |
| フリーエリア | 任意 | 自由入力欄（HTML使用可能）。 |
| 商品削除フラグ | 任意 | 0（通常 / デフォルト）、1（商品削除）。 |
| 商品画像 | 任意 | ファイル名またはURLをカンマ区切りで複数指定可能。 例: item01.jpg,https://example.com/item02.png |
| 商品カテゴリ(ID) | 任意 | 所属させるカテゴリID。カンマ区切りで複数指定可能（例: 1,5,12）。 |
| タグ(ID) | 任意 | 商品タグID（例: 1,2）。 |
| 規格1(ID) / 規格2(ID) | 任意 | 規格分類ID（カラーやサイズ等のID）。単一商品の場合は空欄。 |
| 発送日目安(ID) | 任意 | 発送日目安のID（例: 1（1〜2日で発送））。 |
| 商品コード | 任意 | SKUコード（例: TSHIRT-BLK-M）。重複登録は自動検証されます。 |
| 在庫数 | 任意 | 半角数値で在庫数を指定（例: 100）。 |
| 在庫無制限フラグ | 任意 | 1（在庫無制限）、0（在庫管理を行う）。 |
| 通常価格 | 任意 | メーカー希望小売価格など（半角数値）。 |
| 販売価格 | 必須 | 実売価格（半角数値、例: 2980）。 |
4. ドライラン（検証モード）の使い方
ドライラン (テスト実行) を有効にしてインポートを実行すると、データベースへの書き込みを行わずに、全行のバリデーション（整合性チェック）のみを高速実行します。
ドライランでチェックされる主な項目
- 必須項目の未入力チェック：商品名、公開ステータス、販売価格など
- ID存在チェック：存在しないカテゴリID、タグID、公開ステータスID、規格IDの指定
- データ型チェック：価格や在庫数への文字列混入、不正な数値フォーマット
- SKUコード一意性チェック：既に別商品で使用されている商品コードとの重複
- 画像URL・ファイル名形式チェック：不正なプロトコルや破損リンクの検出
5. 画像登録（URL自動保存 & ZIP一括展開）
商品画像は、外部URLからの自動取得と、ローカルZIPファイルの一括展開の2つの方法に完全対応しています。
1. URL自動ダウンロード（HTTP/HTTPS）
CSVの「商品画像」列に https://example.com/images/sample.jpg のように外部URLを記載し、インポート画面で「URL画像自動ダウンロード」にチェックを入れて実行します。
- プラグインが cURL Multi（並列非同期通信） を用いてバックグラウンドで画像を一括取得します。
- 取得した画像は EC-CUBE の保存ディレクトリ（
html/upload/save_image/）に自動保存され、ファイル名がimg_[hash].jpgとして商品に紐付けられます。 - 同一URLが複数行で使用されている場合でも、自動キャッシュにより無駄な重複ダウンロードを防ぎます。
2. 商品画像ZIPファイルの同時アップロード
手元にある画像ファイルをまとめて images.zip に圧縮し、インポートフォームの「商品画像ZIPファイル」に添付してアップロードします。
- CSV内の「商品画像」列には
photo1.jpg,photo2.jpgのようにZIP内のファイル名を指定します。 - ZIP Slip脆弱性を防ぐセキュア設計で、瞬時に展開して商品へマッピングされます。
6. 分割処理（チャンク実行）と負荷対策
数千〜数万行の大規模CSVインポート時、Webサーバーの最大実行時間（max_execution_time）制限やプロキシのTimeout（504 Gateway Timeout）を回避するため、AJAX再帰的分割処理を採用しています。
1回あたりの処理件数（バッチサイズ）の選び方
| 設定件数 | 推奨される利用環境 | 特徴・メリット |
|---|---|---|
| 20件 / 回 | 共用レンタルサーバー / URL画像DL多数 | サーバー負荷を極小化。タイムアウトのリスクを完全にゼロにします。 |
| 50件 / 回 (標準) | 一般的なVPS / クラウド環境 | 速度と安定性のバランスが最も優れた推奨設定です。 |
| 100件 / 回 | 専用サーバー / テキストのみの大量CSV | 画像DLがない場合の最速インポート設定。 |
$entityManager->clear() を自動実行し、PHPメモリ使用量を常時30MB以下に抑制します。7. エラー行CSV出力と修正手順
インポート中またはドライラン完了時にエラー行が検出された場合、結果バナーに「エラー行CSVをダウンロード」ボタンが表示されます。
「エラー行CSVをダウンロード」をクリックすると、エラーが発生した行のみが抽出されたCSV（error_rows_job_X.csv）が保存されます。
CSVの最終列に『【エラー原因 / Error Reasons】』が追加されています（例: 行 15: カテゴリID [99] が見つかりません。 | 販売価格が正しく入力されていません。）。該当セルを修正します。
最終列のエラー原因列は自動で無視されるため、修正したファイルをそのまま再アップロードするだけで残りのデータが正常登録されます。
8. CSVインポート履歴管理・削除
商品管理 ＞ 商品CSV Pro ＞ インポート履歴を見る（または /admin/product/csv_pro/history）から、過去のすべてのインポート履歴を確認できます。
1. ページネーションと表示件数変更
- 1ページあたりの表示件数を 10件・20件・50件・100件 から選択可能。
- ページ送りと総件数表示により、膨大な履歴が蓄積しても画面読み込みが遅くなりません。
2. 履歴の個別削除 & 全履歴一括削除
- 各履歴行の右側にある ゴミ箱アイコン をクリックすると、その回のログおよびサーバー内の一時ファイルを削除できます。
- 右上の「全履歴削除」ボタンから、過去の履歴ログを一括クリーンアップしてサーバーディスク容量を節約できます（※登録された商品データは削除されません）。