---

name: shopware6-best-practices description: Comprehensive Shopware 6.6+ development best practices for agency developers. Covers backend PHP, storefront Twig/JS, administration Vue.js, app system, integrations, CLI, multi-channel, and DevOps. Triggers on tasks involving plugin development, storefront customization, admin modules, app creation, payment/shipping integrations, or deployment. license: MIT metadata: author: shopware-engineering version: "2.0.0"

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