Back to Details

shopware6-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopware 6 Best Practices

Shopware 6 开发最佳实践

Comprehensive best practices guide for Shopware 6.6+ development, designed for AI agents and LLMs helping agency developers. Contains 77 rules across 22 categories, prioritized by impact to guide automated refactoring and code generation.
这份Shopware 6.6+开发最佳实践指南内容全面，专为协助代理开发者的AI Agent与大语言模型设计。包含22个分类下的77条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:
  • Developing custom Shopware 6 plugins
  • Creating or modifying Store API or Admin API endpoints
  • Working with the Data Abstraction Layer (DAL)
  • Implementing event subscribers and decorators
  • Configuring message queue handlers
  • Writing database migrations
  • Optimizing performance (caching, Elasticsearch)
  • Implementing security measures
  • Writing unit and integration tests
  • Customizing storefront templates and JavaScript
  • Building administration modules and components
  • Creating Shopware apps with webhooks and actions
  • Implementing payment or shipping integrations
  • Building CMS elements and blocks
  • Creating CLI commands for automation
  • Setting up multi-channel or B2B shops
  • Configuring development environments and CI/CD
在以下场景中可参考本指南：
  • 开发自定义Shopware 6插件
  • 创建或修改Store API或Admin API端点
  • 操作数据抽象层（DAL）
  • 实现事件订阅器与装饰器
  • 配置消息队列处理器
  • 编写数据库迁移脚本
  • 优化性能（缓存、Elasticsearch）
  • 实施安全措施
  • 编写单元测试与集成测试
  • 定制店面模板与JavaScript
  • 构建管理端模块与组件
  • 通过Webhook与动作创建Shopware应用
  • 实现支付或物流集成
  • 构建CMS元素与区块
  • 创建用于自动化的CLI命令
  • 搭建多渠道或B2B店铺
  • 配置开发环境与CI/CD

Rule Categories by Priority

按优先级划分的规则分类

PriorityCategoryImpactPrefix
1Plugin ArchitectureCRITICAL
plugin-
2Customization & ExtensionCRITICAL
custom-
3Performance & CachingCRITICAL
perf-
4SecurityCRITICAL
security-
5Data Abstraction LayerHIGH
dal-
6API DevelopmentHIGH
api-
7TestingHIGH
test-
8Event SystemMEDIUM-HIGH
event-
9Database & MigrationsMEDIUM-HIGH
db-
10Message QueueMEDIUM
queue-
11Dependency InjectionMEDIUM
di-
12LoggingMEDIUM
logging-
13ConfigurationMEDIUM
config-
14Scheduled TasksMEDIUM
scheduled-
15Storefront DevelopmentHIGH
storefront-
16Administration DevelopmentHIGH
admin-
17App SystemHIGH
app-
18Integration PatternsHIGH
integration-
19CLI CommandsMEDIUM
cli-
20Multi-Channel & B2BMEDIUM-HIGH
multichannel-
21DevOps & ToolingMEDIUM
devops-
22Common PatternsHIGH
pattern-
优先级分类影响程度前缀
1插件架构关键
plugin-
2定制与扩展关键
custom-
3性能与缓存关键
perf-
4安全关键
security-
5数据抽象层高
dal-
6API开发高
api-
7测试高
test-
8事件系统中高
event-
9数据库与迁移中高
db-
10消息队列中
queue-
11依赖注入中
di-
12日志中
logging-
13配置中
config-
14定时任务中
scheduled-
15店面开发高
storefront-
16管理端开发高
admin-
17应用系统高
app-
18集成模式高
integration-
19CLI命令中
cli-
20多渠道与B2B中高
multichannel-
21DevOps与工具中
devops-
22通用模式高
pattern-

Quick Reference

快速参考

1. Plugin Architecture (CRITICAL)

1. 插件架构（关键）

  • plugin-structure
    - Follow proper plugin directory structure and composer.json
  • plugin-services
    - Register services correctly with proper tags
  • plugin-structure
    - 遵循规范的插件目录结构与composer.json配置
  • plugin-services
    - 正确注册服务并添加合适的标签

2. Customization & Extension (CRITICAL)

2. 定制与扩展（关键）

  • custom-decorator-pattern
    - Use decorator pattern for upgrade-safe service customization
  • custom-event-subscribers
    - Implement event subscribers correctly with proper priorities
  • custom-decorator-pattern
    - 使用装饰器模式实现可安全升级的服务定制
  • custom-event-subscribers
    - 正确实现事件订阅器并设置合适的优先级

3. Performance & Caching (CRITICAL)

3. 性能与缓存（关键）

  • perf-http-cache
    - Configure HTTP cache correctly with proper invalidation
  • perf-dal-optimization
    - Optimize DAL queries to prevent N+1 problems
  • perf-elasticsearch
    - Use Elasticsearch correctly for large catalogs
  • perf-http-cache
    - 正确配置HTTP缓存及失效策略
  • perf-dal-optimization
    - 优化DAL查询以避免N+1问题
  • perf-elasticsearch
    - 针对大型商品目录正确使用Elasticsearch

4. Security (CRITICAL)

4. 安全（关键）

  • security-input-validation
    - Validate all inputs with RequestDataBag and validators
  • security-authentication
    - Implement proper route authentication
  • security-authorization
    - Use ACL for permission checks
  • security-csrf-protection
    - Implement CSRF protection for storefront
  • security-sql-injection
    - Use DAL or parameterized queries
  • security-input-validation
    - 使用RequestDataBag与验证器校验所有输入
  • security-authentication
    - 实现规范的路由认证
  • security-authorization
    - 使用ACL进行权限校验
  • security-csrf-protection
    - 为店面实现CSRF防护
  • security-sql-injection
    - 使用DAL或参数化查询

5. Data Abstraction Layer (HIGH)

5. 数据抽象层（高）

  • dal-criteria-usage
    - Use Criteria objects correctly with filters and pagination
  • dal-associations
    - Load associations explicitly to avoid N+1 queries
  • dal-write-operations
    - Use batch operations and proper sync patterns
  • dal-entity-extensions
    - Extend entities without modifying core
  • dal-custom-entities
    - Create custom entity definitions properly
  • dal-criteria-usage
    - 正确使用Criteria对象实现过滤与分页
  • dal-associations
    - 显式加载关联以避免N+1查询
  • dal-write-operations
    - 使用批量操作与规范的同步模式
  • dal-entity-extensions
    - 在不修改核心代码的前提下扩展实体
  • dal-custom-entities
    - 正确创建自定义实体定义

6. API Development (HIGH)

6. API开发（高）

  • api-store-api-routes
    - Create decoratable Store API routes
  • api-admin-api-routes
    - Create Admin API endpoints with proper ACL
  • api-response-handling
    - Handle responses and errors consistently
  • api-rate-limiting
    - Configure rate limiting for protection
  • api-versioning
    - Version APIs for backwards compatibility
  • api-store-api-routes
    - 创建可被装饰的Store API路由
  • api-admin-api-routes
    - 实现带有规范ACL的Admin API端点
  • api-response-handling
    - 统一处理响应与错误
  • api-rate-limiting
    - 配置限流以提供防护
  • api-versioning
    - 为API添加版本控制以保证向后兼容

7. Testing (HIGH)

7. 测试（高）

  • test-unit-tests
    - Write unit tests with proper mocking
  • test-integration-tests
    - Use IntegrationTestBehaviour correctly
  • test-store-api-tests
    - Test Store API routes with HTTP tests
  • test-fixtures
    - Create reusable test fixtures
  • test-unit-tests
    - 编写带有合理模拟的单元测试
  • test-integration-tests
    - 正确使用IntegrationTestBehaviour
  • test-store-api-tests
    - 通过HTTP测试验证Store API路由
  • test-fixtures
    - 创建可复用的测试夹具

8. Event System (MEDIUM-HIGH)

8. 事件系统（中高）

  • event-business-events
    - Create Flow Builder compatible events
  • event-flow-actions
    - Implement configurable flow actions
  • event-business-events
    - 创建兼容Flow Builder的事件
  • event-flow-actions
    - 实现可配置的流动作

9. Database & Migrations (MEDIUM-HIGH)

9. 数据库与迁移（中高）

  • db-migrations
    - Implement safe database migrations
  • db-migrations
    - 实现安全的数据库迁移

10. Message Queue (MEDIUM)

10. 消息队列（中）

  • queue-message-handlers
    - Implement async message handling
  • queue-worker-config
    - Configure workers for production
  • queue-low-priority
    - Separate low-priority background tasks
  • queue-message-handlers
    - 实现异步消息处理
  • queue-worker-config
    - 为生产环境配置工作进程
  • queue-low-priority
    - 分离低优先级的后台任务

11. Dependency Injection (MEDIUM)

11. 依赖注入（中）

  • di-service-container
    - Use Symfony DI correctly
  • di-service-container
    - 正确使用Symfony依赖注入容器

12. Logging (MEDIUM)

12. 日志（中）

  • logging-best-practices
    - Implement structured logging
  • logging-best-practices
    - 实现结构化日志

13. Configuration (MEDIUM)

13. 配置（中）

  • config-plugin-settings
    - Implement plugin configuration correctly
  • config-plugin-settings
    - 正确实现插件配置

14. Scheduled Tasks (MEDIUM)

14. 定时任务（中）

  • scheduled-tasks
    - Implement reliable scheduled tasks
  • scheduled-tasks
    - 实现可靠的定时任务

15. Storefront Development (HIGH)

15. 店面开发（高）

  • storefront-controller-pattern
    - Extend StorefrontController with page loaders
  • storefront-twig-extension
    - Template inheritance with sw_extends and blocks
  • storefront-js-plugins
    - JavaScript plugin registration and lifecycle
  • storefront-themes
    - Theme structure, inheritance, and configuration
  • storefront-scss-variables
    - SCSS variables and responsive mixins
  • storefront-http-client
    - AJAX requests and Store API calls from JS
  • 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. Administration Development (HIGH)

16. 管理端开发（高）

  • admin-module-structure
    - Module registration, routes, and navigation
  • admin-components
    - Vue component patterns and templates
  • admin-data-handling
    - Repository factory and Criteria API in admin
  • admin-acl-permissions
    - ACL-based UI visibility and actions
  • admin-mixins-composables
    - Mixins, directives, and extensibility
  • admin-extension-api
    - App iframe modules and Extension SDK
  • 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 System (HIGH)

17. 应用系统（高）

  • app-manifest
    - Complete manifest.xml configuration
  • app-webhooks
    - Webhook handling and signature verification
  • app-custom-actions
    - Action buttons with notifications, modals, redirects
  • app-payment-methods
    - App payment handlers for pay/finalize/capture/refund
  • app-custom-fields
    - Custom field definitions via manifest
  • app-scripts
    - Twig-based app scripts and hook points
  • app-manifest
    - 完整的manifest.xml配置
  • app-webhooks
    - Webhook处理与签名验证
  • app-custom-actions
    - 带有通知、模态框与重定向的动作按钮
  • app-payment-methods
    - 应用支付处理器（支持支付/确认/捕获/退款）
  • app-custom-fields
    - 通过manifest定义自定义字段
  • app-scripts
    - 基于Twig的应用脚本与钩子点

18. Integration Patterns (HIGH)

18. 集成模式（高）

  • integration-payment-handler
    - Sync/async payment handler patterns
  • integration-shipping-method
    - Shipping calculators and delivery times
  • integration-cms-elements
    - CMS element creation with data resolvers
  • integration-import-export
    - Import/export profiles and converters
  • integration-external-api
    - HTTP client patterns with retry and caching
  • integration-payment-handler
    - 同步/异步支付处理器模式
  • integration-shipping-method
    - 物流计算器与配送时间
  • integration-cms-elements
    - 带有数据解析器的CMS元素创建
  • integration-import-export
    - 导入/导出配置文件与转换器
  • integration-external-api
    - 带有重试与缓存的HTTP客户端模式

19. CLI Commands (MEDIUM)

19. CLI命令（中）

  • cli-commands
    - Custom command creation with arguments and options
  • cli-command-lifecycle
    - Configure/initialize/interact/execute lifecycle
  • cli-progress-output
    - SymfonyStyle, progress bars, and formatting
  • cli-commands
    - 创建带有参数与选项的自定义命令
  • cli-command-lifecycle
    - 配置/初始化/交互/执行生命周期
  • cli-progress-output
    - 使用SymfonyStyle、进度条与格式化输出

20. Multi-Channel & B2B (MEDIUM-HIGH)

20. 多渠道与B2B（中高）

  • multichannel-saleschannel
    - Sales channel awareness and visibility
  • multichannel-b2b-patterns
    - Company handling, roles, and budgets
  • multichannel-pricing
    - Currency, customer groups, and tax handling
  • multichannel-context
    - Context types, scopes, and permissions
  • multichannel-saleschannel
    - 销售渠道感知与可见性
  • multichannel-b2b-patterns
    - 企业账户处理、角色与预算
  • multichannel-pricing
    - 货币、客户组与税务处理
  • multichannel-context
    - 上下文类型、作用域与权限

21. DevOps & Tooling (MEDIUM)

21. DevOps与工具（中）

  • devops-development-setup
    - Dockware, docker-compose, Makefile patterns
  • devops-deployment
    - Deployment scripts, builds, and rollbacks
  • devops-static-analysis
    - PHPStan, PHP-CS-Fixer, Rector configuration
  • devops-debugging
    - Profiler, Xdebug, logging, and data collectors
  • devops-ci-cd
    - GitHub Actions and GitLab CI workflows
  • 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. Common Patterns (HIGH)

22. 通用模式（高）

  • pattern-error-handling
    - Custom exceptions and error pages
  • pattern-translations
    - Snippets and entity translations
  • pattern-media-handling
    - Media service, uploads, and thumbnails
  • pattern-rule-builder
    - Custom rule conditions for pricing/shipping
  • pattern-upgrade-migration
    - Version-aware code and update migrations
  • pattern-error-handling
    - 自定义异常与错误页面
  • pattern-translations
    - 代码片段与实体翻译
  • pattern-media-handling
    - 媒体服务、上传与缩略图
  • pattern-rule-builder
    - 用于定价/物流的自定义规则条件
  • pattern-upgrade-migration
    - 版本感知代码与更新迁移

Core Principles

核心原则

The Decorator Pattern is Key

装饰器模式是核心

Never modify core files. Always use:
  • Decorators for services
  • Event subscribers for hooks
  • Entity extensions for data
永远不要修改核心文件。请始终使用：
  • 装饰器用于服务定制
  • 事件订阅器用于钩子
  • 实体扩展用于数据扩展

DAL Over Raw SQL

优先使用DAL而非原生SQL

Use Shopware's Data Abstraction Layer instead of raw SQL:
  • Type safety and validation
  • Automatic association handling
  • Built-in versioning and translation
使用Shopware的数据抽象层（DAL）替代原生SQL：
  • 类型安全与验证
  • 自动关联处理
  • 内置版本控制与翻译

Performance First

性能优先

Shopware can be slow if misused:
  • Enable HTTP cache in production
  • Use Elasticsearch for 10K+ products
  • Load only needed associations
  • Use message queue for heavy tasks
若使用不当，Shopware可能会运行缓慢：
  • 生产环境启用HTTP缓存
  • 商品数量超过10K时使用Elasticsearch
  • 仅加载所需的关联
  • 重型任务使用消息队列

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:
rules/plugin-structure.md
rules/custom-decorator-pattern.md
rules/perf-http-cache.md
rules/security-input-validation.md
rules/dal-criteria-usage.md
Each rule file contains:
  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Additional context and references
阅读单个规则文件获取详细说明与代码示例：
rules/plugin-structure.md
rules/custom-decorator-pattern.md
rules/perf-http-cache.md
rules/security-input-validation.md
rules/dal-criteria-usage.md
每个规则文件包含：
  • 规则重要性的简要说明
  • 错误代码示例及解释
  • 正确代码示例及解释
  • 额外背景与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded: 
AGENTS.md
包含所有规则详细内容的完整指南：
AGENTS.md