shopware6-best-practices

# Shopware 6 Best Practices 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. ## 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 ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Plugin Architecture | CRITICAL | `plugin-` | | 2 | Customization & Extension | CRITICAL | `custom-` | | 3 | Performance & Caching | CRITICAL | `perf-` | | 4 | Security | CRITICAL | `security-` | | 5 | Data Abstraction Layer | HIGH | `dal-` | | 6 | API Development | HIGH | `api-` | | 7 | Testing | HIGH | `test-` | | 8 | Event System | MEDIUM-HIGH | `event-` | | 9 | Database & Migrations | MEDIUM-HIGH | `db-` | | 10 | Message Queue | MEDIUM | `queue-` | | 11 | Dependency Injection | MEDIUM | `di-` | | 12 | Logging | MEDIUM | `logging-` | | 13 | Configuration | MEDIUM | `config-` | | 14 | Scheduled Tasks | MEDIUM | `scheduled-` | | 15 | Storefront Development | HIGH | `storefront-` | | 16 | Administration Development | HIGH | `admin-` | | 17 | App System | HIGH | `app-` | | 18 | Integration Patterns | HIGH | `integration-` | | 19 | CLI Commands | MEDIUM | `cli-` | | 20 | Multi-Channel & B2B | MEDIUM-HIGH | `multichannel-` | | 21 | DevOps & Tooling | MEDIUM | `devops-` | | 22 | Common Patterns | HIGH | `pattern-` | ## Quick Reference ### 1. Plugin Architecture (CRITICAL) - `plugin-structure` - Follow proper plugin directory structure and composer.json - `plugin-services` - Register services correctly with proper tags ### 2. Customization & Extension (CRITICAL) - `custom-decorator-pattern` - Use decorator pattern for upgrade-safe service customization - `custom-event-subscribers` - Implement event subscribers correctly with proper priorities ### 3. Performance & Caching (CRITICAL) - `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 ### 4. Security (CRITICAL) - `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 ### 5. Data Abstraction Layer (HIGH) - `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 ### 6. API Development (HIGH) - `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 ### 7. Testing (HIGH) - `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 ### 8. Event System (MEDIUM-HIGH) - `event-business-events` - Create Flow Builder compatible events - `event-flow-actions` - Implement configurable flow actions ### 9. Database & Migrations (MEDIUM-HIGH) - `db-migrations` - Implement safe database migrations ### 10. Message Queue (MEDIUM) - `queue-message-handlers` - Implement async message handling - `queue-worker-config` - Configure workers for production - `queue-low-priority` - Separate low-priority background tasks ### 11. Dependency Injection (MEDIUM) - `di-service-container` - Use Symfony DI correctly ### 12. Logging (MEDIUM) - `logging-best-practices` - Implement structured logging ### 13. Configuration (MEDIUM) - `config-plugin-settings` - Implement plugin configuration correctly ### 14. Scheduled Tasks (MEDIUM) - `scheduled-tasks` - Implement reliable scheduled tasks ### 15. Storefront Development (HIGH) - `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 ### 16. Administration Development (HIGH) - `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 ### 17. App System (HIGH) - `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 ### 18. Integration Patterns (HIGH) - `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 ### 19. CLI Commands (MEDIUM) - `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 ### 20. Multi-Channel & B2B (MEDIUM-HIGH) - `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 ### 21. DevOps & Tooling (MEDIUM) - `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 ### 22. Common Patterns (HIGH) - `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 ## 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 Use Shopware's Data Abstraction Layer instead of raw SQL: - Type safety and validation - Automatic association handling - Built-in versioning and translation ### 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 ## 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 ## Full Compiled Document For the complete guide with all rules expanded: `AGENTS.md`