shopware6-best-practices

Shopware 6 のベストプラクティス

Shopware 6.6 以降の開発に関する包括的なベストプラクティスガイドです。エージェンシーの開発者を支援する AI エージェントと LLM 向けに設計されています。22 カテゴリーにわたる 77 のルールが含まれており、影響度に基づいて優先順位を付け、リファクタリングの自動化やコード生成の指針となります。

適用する場面

次の作業では、これらのガイドラインを参照してください。

• カスタム Shopware 6 プラグインの開発
• Store API または Admin API エンドポイントの作成や変更
• Data Abstraction Layer（DAL）の利用
• イベントサブスクライバーやデコレーターの実装
• メッセージキューハンドラーの設定
• データベースマイグレーションの作成
• パフォーマンスの最適化（キャッシュ、Elasticsearch）
• セキュリティ対策の実装
• 単体テストや統合テストの作成
• ストアフロントのテンプレートや JavaScript のカスタマイズ
• 管理モジュールやコンポーネントの構築
• Webhook やアクションを備えた Shopware アプリの作成
• 決済や配送の連携の実装
• CMS 要素やブロックの構築
• 自動化用 CLI コマンドの作成
• マルチチャネルまたは B2B ショップの構築
• 開発環境や CI/CD の設定

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	接頭辞
1	プラグインアーキテクチャ	CRITICAL	plugin-
2	カスタマイズと拡張	CRITICAL	custom-
3	パフォーマンスとキャッシュ	CRITICAL	perf-
4	セキュリティ	CRITICAL	security-
5	データ抽象化レイヤー	HIGH	dal-
6	API 開発	HIGH	api-
7	テスト	HIGH	test-
8	イベントシステム	MEDIUM-HIGH	event-
9	データベースとマイグレーション	MEDIUM-HIGH	db-
10	メッセージキュー	MEDIUM	queue-
11	依存性注入	MEDIUM	di-
12	ロギング	MEDIUM	logging-
13	設定	MEDIUM	config-
14	スケジュールタスク	MEDIUM	scheduled-
15	ストアフロント開発	HIGH	storefront-
16	管理機能開発	HIGH	admin-
17	アプリシステム	HIGH	app-
18	連携パターン	HIGH	integration-
19	CLI コマンド	MEDIUM	cli-
20	マルチチャネルと B2B	MEDIUM-HIGH	multichannel-
21	DevOps とツール	MEDIUM	devops-
22	共通パターン	HIGH	pattern-

クイックリファレンス

1. プラグインアーキテクチャ（CRITICAL）

• plugin-structure - 適切なプラグインディレクトリー構成と composer.json に従います
• plugin-services - 適切なタグを付けてサービスを正しく登録します

2. カスタマイズと拡張（CRITICAL）

• custom-decorator-pattern - アップグレードに安全なサービスのカスタマイズにはデコレーターパターンを使用します
• custom-event-subscribers - 適切な優先度でイベントサブスクライバーを正しく実装します

3. パフォーマンスとキャッシュ（CRITICAL）

• perf-http-cache - 適切な無効化を設定し、HTTP キャッシュを正しく構成します
• perf-dal-optimization - N+1 問題を防ぐために DAL クエリを最適化します
• perf-elasticsearch - 大規模なカタログでは Elasticsearch を正しく使用します

4. セキュリティ（CRITICAL）

• security-input-validation - RequestDataBag とバリデーターを使ってすべての入力を検証します
• security-authentication - ルートに適切な認証を実装します
• security-authorization - 権限の確認には ACL を使用します
• security-csrf-protection - ストアフロントに CSRF 対策を実装します
• security-sql-injection - DAL またはパラメーター化クエリを使用します

5. データ抽象化レイヤー（HIGH）

• dal-criteria-usage - フィルターとページネーションを備えた Criteria オブジェクトを正しく使用します
• dal-associations - N+1 クエリを避けるため、関連データを明示的に読み込みます
• dal-write-operations - バッチ操作と適切な同期パターンを使用します
• dal-entity-extensions - コアを変更せずにエンティティを拡張します
• dal-custom-entities - カスタムエンティティ定義を適切に作成します

6. API 開発（高）

• api-store-api-routes - 装飾可能な Store API ルートを作成します
• api-admin-api-routes - 適切な ACL を備えた Admin API エンドポイントを作成します
• api-response-handling - レスポンスとエラーを一貫して処理します
• api-rate-limiting - 保護のためのレート制限を設定します
• api-versioning - 後方互換性を保つために API をバージョン管理します

7. テスト（高）

• test-unit-tests - 適切なモックを使ってユニットテストを作成します
• test-integration-tests - IntegrationTestBehaviour を正しく使用します
• test-store-api-tests - HTTP テストで Store API ルートをテストします
• test-fixtures - 再利用可能なテストフィクスチャを作成します

8. イベントシステム（中〜高）

• event-business-events - Flow Builder 互換のイベントを作成します
• event-flow-actions - 設定可能なフローアクションを実装します

9. データベースとマイグレーション（中〜高）

• db-migrations - 安全なデータベースマイグレーションを実装します

10. メッセージキュー（中）

• queue-message-handlers - 非同期メッセージ処理を実装します
• queue-worker-config - 本番環境向けにワーカーを設定します
• queue-low-priority - 低優先度のバックグラウンドタスクを分離します

11. 依存性注入（中）

• di-service-container - Symfony DI を正しく使用します

12. ロギング（中）

• logging-best-practices - 構造化ロギングを実装します

13. 設定（中）

• config-plugin-settings - プラグイン設定を正しく実装します

14. スケジュールタスク（中）

• scheduled-tasks - 信頼性の高いスケジュールタスクを実装します

15. ストアフロント開発（高）

• storefront-controller-pattern - ページローダーを使って StorefrontController を拡張します
• storefront-twig-extension - sw_extends とブロックを使ったテンプレート継承
• storefront-js-plugins - JavaScript プラグインの登録とライフサイクル
• storefront-themes - テーマの構造、継承、設定
• storefront-scss-variables - SCSS 変数とレスポンシブミックスイン
• storefront-http-client - JS からの AJAX リクエストと Store API 呼び出し

16. 管理画面開発（高）

• admin-module-structure - モジュール登録、ルート、ナビゲーション
• admin-components - Vue コンポーネントのパターンとテンプレート
• admin-data-handling - 管理画面でのリポジトリファクトリーと Criteria API
• admin-acl-permissions - ACL に基づく UI の表示制御とアクション
• admin-mixins-composables - ミックスイン、ディレクティブ、拡張性
• admin-extension-api - アプリの iframe モジュールと Extension SDK

17. アプリシステム（高）

• app-manifest - manifest.xml の完全な設定
• app-webhooks - Webhook の処理と署名の検証
• app-custom-actions - 通知、モーダル、リダイレクトを備えたアクションボタン
• app-payment-methods - 支払い、確定、売上確定、返金に対応するアプリの決済ハンドラー
• app-custom-fields - マニフェストによるカスタムフィールド定義
• app-scripts - Twig ベースのアプリスクリプトとフックポイント

18. 統合パターン（高）

• integration-payment-handler - 同期／非同期の決済ハンドラーパターン
• integration-shipping-method - 配送料計算と配送時間
• integration-cms-elements - データリゾルバーを使った CMS 要素の作成
• integration-import-export - インポート／エクスポートのプロファイルとコンバーター
• integration-external-api - リトライとキャッシュを備えた HTTP クライアントのパターン

19. CLI コマンド（中）

• cli-commands - 引数とオプションを指定したカスタムコマンドの作成
• cli-command-lifecycle - 設定／初期化／対話／実行のライフサイクル
• cli-progress-output - SymfonyStyle、プログレスバー、書式設定

20. マルチチャネルと B2B（中〜高）

• multichannel-saleschannel - 販売チャネルの認識と可視性
• multichannel-b2b-patterns - 企業の処理、役割、予算
• multichannel-pricing - 通貨、顧客グループ、税の処理
• multichannel-context - コンテキストの種類、スコープ、権限

21. DevOps とツール（中）

• devops-development-setup - Dockware、docker-compose、Makefile のパターン
• devops-deployment - デプロイメントスクリプト、ビルド、ロールバック
• devops-static-analysis - PHPStan、PHP-CS-Fixer、Rector の設定
• devops-debugging - プロファイラー、Xdebug、ログ、データコレクター
• devops-ci-cd - GitHub Actions と GitLab CI のワークフロー

22. 一般的なパターン（高）

• pattern-error-handling - カスタム例外とエラーページ
• pattern-translations - スニペットとエンティティの翻訳
• pattern-media-handling - メディアサービス、アップロード、サムネイル
• pattern-rule-builder - 価格設定／配送向けのカスタムルール条件
• pattern-upgrade-migration - バージョン対応コードと更新マイグレーション

コア原則

デコレーターパターンが重要です

コアファイルは変更しないでください。常に以下を使用してください。

• デコレーターでサービスを拡張する
• イベントサブスクライバーでフックを処理する
• エンティティ拡張でデータを拡張する

生 SQL より DAL を使用する

生 SQL の代わりに、Shopware のデータ抽象化レイヤーを使用してください。

• 型安全性と検証
• 関連の自動処理
• 組み込みのバージョン管理と翻訳

パフォーマンスを最優先する

Shopware は誤った使い方をすると遅くなる可能性があります。

• 本番環境では HTTP キャッシュを有効にする
• 商品数が 10K を超える場合は Elasticsearch を使用する
• 必要な関連のみを読み込む
• 負荷の高いタスクにはメッセージキューを使用する

使い方

詳しい説明とコード例については、個々のルールファイルを読んでください。

rules/plugin-structure.md
rules/custom-decorator-pattern.md
rules/perf-http-cache.md
rules/security-input-validation.md
rules/dal-criteria-usage.md

各ルールファイルには以下が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料

コンパイル済みの完全版ドキュメント

すべてのルールを展開した完全なガイドは AGENTS.md を参照してください。