prestashop-module-development

PrestaShop モジュール開発

使用する場面

次のような PrestaShop モジュール開発タスクで、このスキルを使用します。

• モダンなアーキテクチャ（Symfony コントローラー、サービス、エンティティ）を使用した新しいモジュールの作成
• レガシーモジュールをモダンな PrestaShop のパターンに合わせてリファクタリング
• フック、アクション、イベントリスナーの実装
• 設定ページの追加（モダンな Symfony フォーム方式）
• フロントオフィスの機能やウィジェットの作成
• データベースエンティティとマイグレーションの設定
• セキュリティ対策の実装（CSRF、入力検証、SQL インジェクション対策）
• 多言語対応と翻訳の追加
• レガシーコードのパターン（HelperForm、jQuery UI sortable、ObjectModel）をモダンな方法に置き換え
• PrestaShop Grid システムを使った一覧ページの構築（フィルター、ページネーション、切り替え、ドラッグ＆ドロップによる位置変更）
• PrestaShop のカートルール（バウチャー、割引コード、プロモーションコード）の作成と管理
• バックグラウンドタスクやバッチ処理のための Symfony コンソールコマンドの実装

必要な入力

• PrestaShop のバージョン（モダンな開発では 8.x／9.x を対象）
• モジュールの範囲と機能要件
• 既存モジュールのパス（レガシーコードを更新する場合）
• データベーススキーマの要件（該当する場合）
• フロントオフィスとの連携要件（フック、ウィジェット、ページ）
• 設定要件（設定、管理画面）
• 多言語対応の要件と対応言語

手順

0) プロジェクト構成と名前空間の命名

参照：references/module-structure.md

主なルール：

• モジュール名のプレフィックスから PSR-4 名前空間を導出します。PrestaShop\Module\ は使用しないでください
• 新しいモジュールのひな形作成には、PrestaShop Module Generator を使用します

1) メインモジュールクラスとインストーラー

参照：references/module-class-and-installer.md

必須パターン：

• install() メソッド：必ず最初に if (!parent::install()) { return false; } を実行し、その後にインストーラーへ処理を委譲します
• uninstall() メソッド：必ず最初にインストーラーを実行し、その後 && でつないで parent::uninstall() を実行します：return $installer->uninstall() && parent::uninstall();
• フック：Installer のクラスプロパティ配列 private array $hooks = [...] として定義し、$module->registerHook($this->hooks) を使って登録します
• タブ：name、class_name、label、parent_class_name、visible を含む構造化データを持つクラスプロパティ配列 private array $tabs = [...] として定義します
• 親グループタブ：存在するかを自動で確認します。存在しない場合は、array_unshift($this->tabs, $parentTab) でタブ配列の先頭に追加します
• getTabs() は使用しない：モジュールクラスに getTabs() メソッドを追加しないでください。タブ管理はすべて Installer のみに実装します

主なルール：

• _PS_VERSION_ のガードの後に、必ず require_once __DIR__ . '/vendor/autoload.php'; を記述します
• フックの登録、DB クエリ、Configuration:: の呼び出しを install() に直接記述せず、src/Install/Installer.php に処理を委譲します
• getContent() では、モダンな Symfony ルーターを使って Symfony ルートへのリダイレクトのみを行います：$router = $this->get('router'); $route = $router->generate('route_name'); Tools::redirectAdmin($route); — $this->context->link->getAdminLink() は使用しないでください
• メインモジュールクラスに SQL を記述しないでください — フック内（hookActionShopDataDuplication など）やウィジェットメソッド（getWidgetVariables など）での処理も含め、すべてのデータベースアクセスを $this->get('service.id') 経由で Repository または Manager クラスに委譲します
• サービスへのアクセス：管理コンテキストでは $this->has() を使って null チェックを行います。フロントオフィスのコンテキストでは $this->get() のみを使って null チェックを行います。ContainerFinder は使用しないでください — 不要です。references/module-class-and-installer.md の Guard patterns セクションを参照してください。

1b）設定変数の管理

参照：references/configuration-management.md

必須のパターン：ConfigurationManager サービスを使用した YAML ベースの設定

主なルール：

• ビジネスロジックで Configuration::updateValue() または Configuration::get() を直接使用しないでください
• すべての設定キーとデフォルト値を定義するため、必ず /config_data/module.yml を作成してください（信頼できる唯一の情報源）
• インストール／アンインストール操作には、必ず ConfigurationInstaller サービスを使用してください
• 設定の読み取りには、必ず ConfigurationManager サービスを使用してください（データベースまたは YAML のフォールバックから読み取ります）
• 構成：
  • config_data/module.yml — すべてのキーとデフォルト値
  • src/Install/ConfigurationInstaller.php — 設定値のインストール／アンインストール
  • src/Configuration/ConfigurationManager.php — 設定の読み取り（データベースまたは YAML）
  • config/components/configuration/configuration_manager.yml — サービスの登録
• メリット：信頼できる唯一の情報源、型安全なアクセス、ハードコードされたキーが不要、テストと保守が容易

2）最新の設定ページ

参照：references/configuration-page.md

必須のパターン：コンストラクターの依存性注入を使用した FormHandler

主なルール：

• HelperForm は使用しないでください — Symfony フォームコンポーネントと FrameworkBundleAdminController を使用してください
• コントローラーで $this->get() を使ってサービスにアクセスしないでください — コントローラーで利用できるサービスロケーターには制限があります。FormHandler とコンストラクターの依存性注入を使用してください
• 5 つのクラス：DataConfiguration、FormDataProvider、FormType、FormHandler（PrestaShop Core）、Controller（DI 使用）
• config/components/configuration/services.yml（config/admin/services.yml からインポート）と config/routes.yml ですべてを接続してください
• FormHandler：フォームの作成、検証、保存をラップする PrestaShop\PrestaShop\Core\Form\Handler サービスを使用してください
• コントローラーの登録：public: true サービスとして、controller.service_arguments タグを付けて登録する必要があります
• FormType の登録：parent: 'form.type.translatable.aware' と tags: [{ name: form.type }] を設定する必要があります
• Twig テンプレートでのフォームのラップ：必ず {% extends %} より前に {% form_theme configurationForm '@PrestaShop/Admin/TwigTemplateForm/prestashop_ui_kit.html.twig' %} を使用してください。{{ form_start() }} は <div class="card"> より前に、{{ form_end() }} は </div> より後に配置してください。HTML の破損を防ぐため、フォームタグでカード全体を同じ階層のまま囲む必要があります
• コントローラーのパターン：

  private FormHandlerInterface $formHandler;
  
  public function __construct(FormHandlerInterface $formHandler)
  {
      $this->formHandler = $formHandler;
  }
  
  public function indexAction(Request $request): Response
  {
      $form = $this->formHandler->getForm();
      // ... handle request and save via $this->formHandler->save()
  }
  

• CategoryChoiceTreeType：階層型のカテゴリー選択ツリーに使用する PrestaShop のフォームタイプです。次のように設定する必要があります：
  • 有効なフォームオプション：複数選択の場合は 'multiple' => true、任意項目の場合は 'required' => false を指定します。'expanded' オプションはこのタイプには存在しないため、使用しないでください
  • テンプレート要件：{% extends %} ディレクティブより前に {% form_theme configurationForm '@PrestaShop/Admin/TwigTemplateForm/prestashop_ui_kit.html.twig' %} を追加し、{% block javascripts %} に JS バンドルを含めてください
  • JavaScript の初期化：window.prestashop.component.initComponents(['ChoiceTree']) と new window.prestashop.component.ChoiceTree('#form_categories').enableAutoCheckChildren() を記述した views/js/mymodule.form.bundle.js を作成してください。セレクターは HTML の id 属性（通常は form_<field_name>）と一致させる必要があります
  • フォームデータの処理：カテゴリー ID の配列が返されます。implode(',', $data['categories']) でコンマ区切りの文字列として保存し、array_filter(array_map('intval', explode(',', $storedValue))) で取得して元に戻してください
  • よくある問題：ツリーが通常のチェックボックスとして表示される → フォームテーマがありません。展開／折りたたみが機能しない → JS の初期化がありません。「ChoiceTree is not defined」 → ChoiceTree をそのまま使わず、window.prestashop.component.ChoiceTree を使用してください

3) データベース操作とエンティティ

参照：references/database-and-entities.md
翻訳可能なエンティティでGridを使用する場合は、references/entity-doctrine.mdを参照してください。

• Gridの一覧ページまたは翻訳可能なフィールドを持つエンティティには、必ずDoctrine ORM（Entity + LangEntity + Repository + Manager）を使用してください。
• ObjectModelはレガシーです。新規モジュールやモダナイズするモジュールでは使用しないでください。
• エンティティクラス名 = _DB_PREFIX_を除いたテーブル名です。PSがグローバルにプレフィックスを追加するため、name=パラメーターなしで@ORM\Table()を使用してください。
• テーブル名には一貫した会社またはモジュールのプレフィックス（例：prefix_mymodule_items、prefix_mymodule_items_lang）を付けてください。これにより、テーブルをまとめて管理し、PSコアテーブルとの競合を避けられます。
• Langエンティティのプロパティ型はDB列のNULL許容設定と一致させてください。NOT NULL DEFAULT ''と宣言された列にはstring $field = ''を、NULLと宣言された列には?string $field = nullを使用してください。
• TranslatableTypeは、ユーザーが入力していない言語ではnullを返します。Managerでは、NOT NULLの文字列フィールドについて、必ずnullを''に変換してください：$row->setName((string) ($value ?? ''))。NOT NULL列のセッターにフォームの値をそのまま渡さないでください。
• テーブル名のためにMetadataListenerやDoctrineイベントリスナーを作成しないでください。
• 未加工のDBAL SQLは必ずサニタイズしてください。IDは(int)でキャストし、バインドパラメーターを使用してください。
• RepositoryクラスとManagerクラス以外では、生のSQL（Db::getInstance()、pSQL()、_DB_PREFIX_の文字列連結）を使用しないでください。 これはメインモジュールクラス、Installer、FixturesInstaller、フック、ウィジェットメソッドを含む、すべての場所に適用されます。唯一の例外は、Repositoryに相当するものがないInstallerのSQLスキーマクエリ（CREATE TABLE、DROP TABLE）です。
• FixturesInstallerではDb::getInstance()による生のSQLを使用してください。SymfonyContainer::getInstance()はpr:mo Symfonyコンソールのコンテキストではnullを返します（global $kernelが設定されないため）。インストール時には、Doctrine ORMの呼び出しはすべて何もせずに終了します。references/module-class-and-installer.mdのFixturesInstallerセクションを参照してください。
• Db::getValue()は内部でLIMIT 1を追加します。渡すSQL文字列にLIMIT 1を書かないでください。MariaDBの構文エラーの原因になります。

サービスの分割とコンポーネントアーキテクチャ

参照：references/services-split.md

主なルール：

• config/services.ymlを作成しないでください。必要なのはconfig/admin/services.ymlとconfig/front/services.ymlのみです。ルートレベルのconfig/services.ymlは不要であり、存在してはなりません。
• config/admin/services.ymlは管理カーネルのみで読み込まれます。../common.ymlと管理コンポーネントをインポートしてください（../プレフィックスなしでcommon.ymlを指定しないでください）。
• Repositoryサービスは、config/common.ymlのコンポーネントにのみ配置してください（Doctrineレベルで、PrestaShopBundleへの依存なし）。
• PrestaShopBundleに依存するサービスは、すべてconfig/admin/services.ymlに配置してください。
• config/components/配下のコンポーネント別サブフォルダーに必ず分割してください。フラットなservices.ymlを1つだけ作成しないでください。
• $this->get('service.id')経由でアクセスするサービスのみ、public: trueが必要です。このような各サービスに明示的に宣言し、それ以外のサービスは非公開のままにしてください（public:を省略）。_defaults: public: trueを一律に指定しないでください。これはSymfonyのベストプラクティスに反し、PrestaShopのSymfonyバージョンではparent:サービスと組み合わせたときに致命的なエラーが発生します。
• parent:を使用し、公開する必要があるサービスは、サービス定義で明示的にpublic: trueを宣言してください。parentが設定されている場合、publicは_defaultsから継承できません（PrestaShopのSymfonyバージョンではこれが強制されます）。
• config/services.ymlからadmin/services.ymlを参照しないでください。これにより管理専用のサービスがフロントカーネルに読み込まれ、コンテナのコンパイルが失敗し、すべての$this->get()呼び出しが何もせずに失敗します。

4) セキュリティ（必須）

参照：references/security.md

• CSRF：Symfonyフォームが自動的に処理します。生のAJAXエンドポイントでは手動で検証してください。
• SQLインジェクション：すべての値に(int) + pSQL()を適用するか、DbQueryビルダーを使用してください。
• ファイルアップロード：type、size、errorを含む、$_FILESと互換性のある配列全体をImageManager::validateUpload()に渡してください。

5) フックとフロントオフィスの連携

参照：references/hooks-and-front-office.md

• 重要：フロントオフィスの CSS／JS を登録する場合は、必ず actionFrontControllerSetMedia フックを使用してください。 header や displayHeader は絶対に使用しないでください。このフック内で $this->context->controller->registerStylesheet() と ->registerJavascript() を使用してください
• フックは install() に直接登録せず、Installer で登録してください
• WidgetInterface を実装する場合、renderWidget() を呼び出すだけの hookDisplayHome() など、明示的なフックメソッドを定義しないでください。 PrestaShop は登録されたすべての表示フックに対して、自動的に renderWidget() を呼び出します
• フロントオフィスの Smarty テンプレートでは、テンプレート内で {l s='Text' d='Modules.Modulename.Front'} を直接使用してください。 getWidgetVariables() から Smarty 変数として翻訳済みの文字列を渡すことは絶対に避けてください。渡すのは動的なデータ（URL、ID など）のみにし、翻訳対象の固定 UI テキストは渡さないでください

5b) テーマテンプレートへの挿入（インストール時のウィジェット呼び出し）

参照：references/theme-template-injection.md

• PS8 はモジュールからのテーマオーバーライドをサポートしていません。代わりにマーカー方式のファイルパッチを使用してください
• 2 クラス構成：ThemeTemplateInjector（再利用可能なサービス）＋ ThemeTemplateInstaller（インストールのオーケストレーター）
• インストール処理では Theme::getThemes() を絶対に使用しないでください。 Symfony コンソールではレガシークラスがオートロードされないため、代わりに scandir(_PS_ALL_THEMES_DIR_) を使用してください
• インストール／アンインストールの呼び出しは try/catch で囲み、true を返してください。テーマへの挿入によってモジュールのインストールが妨げられてはなりません

6) 翻訳

参照：references/translations.md

• FrameworkBundleAdminController::trans() のシグネチャは trans($id, $domain, $parameters = []) です。Symfony の引数順とは異なります。 必ず $this->trans('Text', 'Modules.Mymodule.Admin') のように呼び出してください（$this->trans('Text', [], 'Domain') は使用しないでください。ドメインに [] を、$parameters に文字列を渡すと、型エラーで致命的なエラーが発生します）
• Twig では 'Text'|trans({}, 'Modules.Mymodule.Admin') を使用してください
• モジュールクラスで isUsingNewTranslationSystem(): true を宣言してください

7) レガシーコードの変換

参照：references/legacy-conversion.md

一般的な変換：HelperForm → Symfony form、jQuery UI sortable → Grid PositionColumn、ModuleAdminController → FrameworkBundleAdminController。

8) サービスと依存性注入

参照：references/services-and-di.md

重要：サービス／コントローラーではレガシーの静的呼び出しを絶対に使用しないでください。

• ❌ Context::getContext() — 代わりに $context: "@=service('prestashop.adapter.legacy.context').getContext()" を注入してください
• ❌ Configuration::get()／updateValue() — 代わりに @prestashop.adapter.legacy.configuration を注入してください
• ❌ Context::getContext()->getTranslator() — 代わりに @translator を注入してください

主なルール：

• サービスは config/components/ のサブフォルダーに定義します（config/admin/services.yml からインポートされます）
• Symfony コントローラーでは $this->get('service.id') を使用します
• 計算されたコンストラクター引数（コンテキスト、言語 ID、ショップ ID）には Expression Language（@=）を使用します
• 依存関係は必ずコンストラクター経由で注入し、静的アクセサーは使用しないでください

Symfony コンソールコマンド

参照：references/services-and-di.md → Symfony コンソールコマンド セクション

重要：コマンドは config/admin/services.yml に登録する必要があります（common.yml や front/services.yml ではありません）。

# config/admin/services.yml
mymodule.command.my_command:
  class: Vendor\MyModule\Command\MyCommand
  arguments: ["@mymodule.service.my_service"]
  tags:
    - { name: console.command, command: modulename:action }

主なルール：

• コマンド名：modulename:action 形式（例：wsautocartrules:create、ws_keepdblight:cleandb）
• 戻り値コード：成功時は 0、失敗時は 1（Command::SUCCESS／FAILURE 定数ではありません）
• 表（テーブル）、進捗バー、スタイル付きメッセージなど、充実したコンソール出力には SymfonyStyle を使用します
• 小規模なデータセットでテストできるよう、バッチ処理には --limit オプションを追加します
• サービスは必ずコンストラクター経由で注入し、静的呼び出しや $this->get() は使用しないでください

9) カートルールとバウチャー

参照：references/cart-rules.md

PrestaShop のカートルール（割引バウチャー）をプログラムで作成、管理するための完全ガイドです。

主なパターン：

• コード生成：文字セット 123456789ABCDEFGHIJKLMNPQRSTUVWXYZ を使用します（混同を避けるため O/0 は含めません。PrestaShop の admin.js と同じです）。
• 一意性チェック：作成前に CartRule::getIdByCode($code) で検証します。
• 多言語名：Language::getLanguages(true) を使用して、すべての有効な言語の name を設定します。
• 顧客の制限：顧客固有のバウチャーには $cartRule->id_customer を使用します。
• 日付範囲：date_from と date_to の両方が必須です（形式：Y-m-d H:i:s）。
• 割引タイプ：reduction_percent、reduction_amount、free_shipping、または gift_product。
• 必須フィールド：quantity、quantity_per_user、priority、highlight、partial_use、active。
• 制限：デフォルトではすべて false（制限なし）です。必要に応じて個別の制限を設定します。

ドキュメントに記載されている一般的な用途：

• 割引率を指定した顧客固有のバウチャー
• 自動適用されるカートルール（コード不要）
• 強調表示付きの期間限定フラッシュセール
• 送料無料バウチャー
• ギフト商品バウチャー

10) グリッドシステム（ドラッグ＆ドロップで並べ替えられる一覧ページ）

参照：references/grid-system.md

PS Grid システムを使用して CRUD 一覧ページを構築するための完全なパターンです。

• GridDefinitionFactory — 列（PositionColumn、ToggleColumn、ActionColumn）、フィルター、行アクション
• QueryBuilder — ソート、ページネーション、フィルターに対応した Doctrine DBAL クエリ
• Filters — デフォルトのソート／件数設定
• config/components/grid/ に 5 つのサービス定義（factory、query、data、grid、position）＋ Twig FilesystemLoader 1 つ
• Twig FilesystemLoader のパスは %kernel.project_dir%/modules/mymodule/views です — %kernel.project_dir% は PS のルート（app/ の親）なので、modules/ は直下にあります。%kernel.project_dir%/../modules/ は使用しないでください。
• routes.yml に 4 つのルート（index、search、toggle、update-position）
• 4 つのコントローラーアクション（indexAction、searchAction、toggleStatus、updatePositionAction）
• 汎用グリッドスクリプト scripts/grid.bundle.js を views/js/{modulename}.bundle.js としてコピーします — 編集もグリッド ID の指定も不要です（コアの window.prestashop.component Grid と拡張機能を使用。PS 8.0+ / 9.x）

検証

• モジュールが PHP エラーなしでインストールされること：php bin/console pr:mo install mymodule
• 設定が適切な検証とともに正しく保存されること
• フロントオフィスの機能が正しく表示され、動作すること
• 設定済みのすべての言語で翻訳が機能すること

バリデーション

AI エージェントのルール — どちらの手順も絶対に省略しないでください。詳しい手順は references/validation.md を参照してください。

手順 1 — lotr（モジュールのルートから実行）

vendor/websenso/prestashop-module-devtools/bin/lotr

期待される結果：🎉 All commands completed successfully! Executed: 6/6

手順 2 — インストールテスト（PS のルートから実行）

php bin/console pr:mo install mymodule

期待される結果：L'action Install sur le module … a réussi.

失敗事例／デバッグ

参照：references/debugging.md

よくある問題箇所：

• references/debugging.md — 症状／原因／対処法の表（インストール、設定ページ、Grid、InputBag、ImageManager、lotr の手順）

PrestaShop 9 コアドキュメント

以下のファイルは、このスキルに ps9-core-ai/ ディレクトリ内で同梱されています。 PS9 のコアアーキテクチャ、規約、パターンを深く理解するために参照してください。

• ps9-core-ai/CONTEXT.md — PS9 コードベースのルート AI コンテキスト：プロジェクト全体のコーディング標準、アーキテクチャレイヤー（Core/Adapter/Bundle/Legacy）、CQRS パターン、ブランチポリシー、およびドメインとコンポーネントのコンテキストの完全なインデックス。
• ps9-core-ai/STRUCTURE.md — .ai/ フォルダー自体のアーキテクチャ：コンテキスト、スキル、ポインターファイルの整理方法と、AI ツールによる検出方法。

スキルメンテナーへの注意：これらのファイルは、PrestaShop 公式リポジトリの静的スナップショットです。更新するには、スキルメンテナーがモジュールディレクトリから lotr --install を実行できます。これは実行時の操作ではありません。ファイルは事前にバンドルされ、スキルとともにバージョン管理されています。

ステアリング

プロジェクトまたは組織でステアリング層（コーディング規約、アーキテクチャ規約、プロジェクト固有の上書きを定める階層化されたコンテキストルール）を定義している場合は、タスクを開始する前にステアリングファイルを読み込んでください。

リゾルバーの検索順序：

1. モジュールのルートにある steering/resolver.md（カスタムインストール）
2. vendor/websenso/prestashop-module-devtools/steering/resolver.md — devtools を Composer パッケージとしてインストールした場合の標準パス（vendor/websenso/prestashop-module-devtools/bin/lotr を提供するものと同じパッケージ）
3. vendor/*/*/steering/resolver.md — すべての vendor サブフォルダーを検索し、steering/resolver.md ファイルを探します（最初に見つかったものを使用）

見つからない場合は、ステアリングを読み込まずにスキップし、スキルのデフォルトのみを適用してください。

一般的なステアリング構成（パスはリゾルバーが見つかった場所からの相対パス）：

steering/resolver.md                          ← load order and conflict rules
steering/company/                             ← organisation-wide standards
steering/languages/php/coding-standards.md    ← PHP conventions
steering/frameworks/prestashop/               ← PrestaShop-specific rules

ステアリングファイルは優先度の低いものから高いものへ（会社 → 言語 → フレームワーク → プロジェクト）読み込んでください。後のレイヤーが前のレイヤーを上書きします。

エスカレーション

• PrestaShop 9 モジュールの作成
• モジュールのベストプラクティス
• 公式サンプルモジュール
• demosymfonyform — Symfony フォーム設定の標準ページ
• モジュールバリデーター
• PrestaShop 開発者 Slack