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
1---
2name: shopware6-best-practices
3description: 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.
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/bartundmett/shopware6-best-practices
7 author: shopware-engineering
8 version: "2.0.0"
9---
10
11# Shopware 6 Best Practices
12
13Comprehensive 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.
14
15## When to Apply
16
17Reference these guidelines when:
18- Developing custom Shopware 6 plugins
19- Creating or modifying Store API or Admin API endpoints
20- Working with the Data Abstraction Layer (DAL)
21- Implementing event subscribers and decorators
22- Configuring message queue handlers
23- Writing database migrations
24- Optimizing performance (caching, Elasticsearch)
25- Implementing security measures
26- Writing unit and integration tests
27- Customizing storefront templates and JavaScript
28- Building administration modules and components
29- Creating Shopware apps with webhooks and actions
30- Implementing payment or shipping integrations
31- Building CMS elements and blocks
32- Creating CLI commands for automation
33- Setting up multi-channel or B2B shops
34- Configuring development environments and CI/CD
35
36## Rule Categories by Priority
37
38| Priority | Category | Impact | Prefix |
39|----------|----------|--------|--------|
40| 1 | Plugin Architecture | CRITICAL | `plugin-` |
41| 2 | Customization & Extension | CRITICAL | `custom-` |
42| 3 | Performance & Caching | CRITICAL | `perf-` |
43| 4 | Security | CRITICAL | `security-` |
44| 5 | Data Abstraction Layer | HIGH | `dal-` |
45| 6 | API Development | HIGH | `api-` |
46| 7 | Testing | HIGH | `test-` |
47| 8 | Event System | MEDIUM-HIGH | `event-` |
48| 9 | Database & Migrations | MEDIUM-HIGH | `db-` |
49| 10 | Message Queue | MEDIUM | `queue-` |
50| 11 | Dependency Injection | MEDIUM | `di-` |
51| 12 | Logging | MEDIUM | `logging-` |
52| 13 | Configuration | MEDIUM | `config-` |
53| 14 | Scheduled Tasks | MEDIUM | `scheduled-` |
54| 15 | Storefront Development | HIGH | `storefront-` |
55| 16 | Administration Development | HIGH | `admin-` |
56| 17 | App System | HIGH | `app-` |
57| 18 | Integration Patterns | HIGH | `integration-` |
58| 19 | CLI Commands | MEDIUM | `cli-` |
59| 20 | Multi-Channel & B2B | MEDIUM-HIGH | `multichannel-` |
60| 21 | DevOps & Tooling | MEDIUM | `devops-` |
61| 22 | Common Patterns | HIGH | `pattern-` |
62
63## Quick Reference
64
65### 1. Plugin Architecture (CRITICAL)
66
67- `plugin-structure` - Follow proper plugin directory structure and composer.json
68- `plugin-services` - Register services correctly with proper tags
69
70### 2. Customization & Extension (CRITICAL)
71
72- `custom-decorator-pattern` - Use decorator pattern for upgrade-safe service customization
73- `custom-event-subscribers` - Implement event subscribers correctly with proper priorities
74
75### 3. Performance & Caching (CRITICAL)
76
77- `perf-http-cache` - Configure HTTP cache correctly with proper invalidation
78- `perf-dal-optimization` - Optimize DAL queries to prevent N+1 problems
79- `perf-elasticsearch` - Use Elasticsearch correctly for large catalogs
80
81### 4. Security (CRITICAL)
82
83- `security-input-validation` - Validate all inputs with RequestDataBag and validators
84- `security-authentication` - Implement proper route authentication
85- `security-authorization` - Use ACL for permission checks
86- `security-csrf-protection` - Implement CSRF protection for storefront
87- `security-sql-injection` - Use DAL or parameterized queries
88
89### 5. Data Abstraction Layer (HIGH)
90
91- `dal-criteria-usage` - Use Criteria objects correctly with filters and pagination
92- `dal-associations` - Load associations explicitly to avoid N+1 queries
93- `dal-write-operations` - Use batch operations and proper sync patterns
94- `dal-entity-extensions` - Extend entities without modifying core
95- `dal-custom-entities` - Create custom entity definitions properly
96
97### 6. API Development (HIGH)
98
99- `api-store-api-routes` - Create decoratable Store API routes
100- `api-admin-api-routes` - Create Admin API endpoints with proper ACL
101- `api-response-handling` - Handle responses and errors consistently
102- `api-rate-limiting` - Configure rate limiting for protection
103- `api-versioning` - Version APIs for backwards compatibility
104
105### 7. Testing (HIGH)
106
107- `test-unit-tests` - Write unit tests with proper mocking
108- `test-integration-tests` - Use IntegrationTestBehaviour correctly
109- `test-store-api-tests` - Test Store API routes with HTTP tests
110- `test-fixtures` - Create reusable test fixtures
111
112### 8. Event System (MEDIUM-HIGH)
113
114- `event-business-events` - Create Flow Builder compatible events
115- `event-flow-actions` - Implement configurable flow actions
116
117### 9. Database & Migrations (MEDIUM-HIGH)
118
119- `db-migrations` - Implement safe database migrations
120
121### 10. Message Queue (MEDIUM)
122
123- `queue-message-handlers` - Implement async message handling
124- `queue-worker-config` - Configure workers for production
125- `queue-low-priority` - Separate low-priority background tasks
126
127### 11. Dependency Injection (MEDIUM)
128
129- `di-service-container` - Use Symfony DI correctly
130
131### 12. Logging (MEDIUM)
132
133- `logging-best-practices` - Implement structured logging
134
135### 13. Configuration (MEDIUM)
136
137- `config-plugin-settings` - Implement plugin configuration correctly
138
139### 14. Scheduled Tasks (MEDIUM)
140
141- `scheduled-tasks` - Implement reliable scheduled tasks
142
143### 15. Storefront Development (HIGH)
144
145- `storefront-controller-pattern` - Extend StorefrontController with page loaders
146- `storefront-twig-extension` - Template inheritance with sw_extends and blocks
147- `storefront-js-plugins` - JavaScript plugin registration and lifecycle
148- `storefront-themes` - Theme structure, inheritance, and configuration
149- `storefront-scss-variables` - SCSS variables and responsive mixins
150- `storefront-http-client` - AJAX requests and Store API calls from JS
151
152### 16. Administration Development (HIGH)
153
154- `admin-module-structure` - Module registration, routes, and navigation
155- `admin-components` - Vue component patterns and templates
156- `admin-data-handling` - Repository factory and Criteria API in admin
157- `admin-acl-permissions` - ACL-based UI visibility and actions
158- `admin-mixins-composables` - Mixins, directives, and extensibility
159- `admin-extension-api` - App iframe modules and Extension SDK
160
161### 17. App System (HIGH)
162
163- `app-manifest` - Complete manifest.xml configuration
164- `app-webhooks` - Webhook handling and signature verification
165- `app-custom-actions` - Action buttons with notifications, modals, redirects
166- `app-payment-methods` - App payment handlers for pay/finalize/capture/refund
167- `app-custom-fields` - Custom field definitions via manifest
168- `app-scripts` - Twig-based app scripts and hook points
169
170### 18. Integration Patterns (HIGH)
171
172- `integration-payment-handler` - Sync/async payment handler patterns
173- `integration-shipping-method` - Shipping calculators and delivery times
174- `integration-cms-elements` - CMS element creation with data resolvers
175- `integration-import-export` - Import/export profiles and converters
176- `integration-external-api` - HTTP client patterns with retry and caching
177
178### 19. CLI Commands (MEDIUM)
179
180- `cli-commands` - Custom command creation with arguments and options
181- `cli-command-lifecycle` - Configure/initialize/interact/execute lifecycle
182- `cli-progress-output` - SymfonyStyle, progress bars, and formatting
183
184### 20. Multi-Channel & B2B (MEDIUM-HIGH)
185
186- `multichannel-saleschannel` - Sales channel awareness and visibility
187- `multichannel-b2b-patterns` - Company handling, roles, and budgets
188- `multichannel-pricing` - Currency, customer groups, and tax handling
189- `multichannel-context` - Context types, scopes, and permissions
190
191### 21. DevOps & Tooling (MEDIUM)
192
193- `devops-development-setup` - Dockware, docker-compose, Makefile patterns
194- `devops-deployment` - Deployment scripts, builds, and rollbacks
195- `devops-static-analysis` - PHPStan, PHP-CS-Fixer, Rector configuration
196- `devops-debugging` - Profiler, Xdebug, logging, and data collectors
197- `devops-ci-cd` - GitHub Actions and GitLab CI workflows
198
199### 22. Common Patterns (HIGH)
200
201- `pattern-error-handling` - Custom exceptions and error pages
202- `pattern-translations` - Snippets and entity translations
203- `pattern-media-handling` - Media service, uploads, and thumbnails
204- `pattern-rule-builder` - Custom rule conditions for pricing/shipping
205- `pattern-upgrade-migration` - Version-aware code and update migrations
206
207## Core Principles
208
209### The Decorator Pattern is Key
210
211Never modify core files. Always use:
212- **Decorators** for services
213- **Event subscribers** for hooks
214- **Entity extensions** for data
215
216### DAL Over Raw SQL
217
218Use Shopware's Data Abstraction Layer instead of raw SQL:
219- Type safety and validation
220- Automatic association handling
221- Built-in versioning and translation
222
223### Performance First
224
225Shopware can be slow if misused:
226- Enable HTTP cache in production
227- Use Elasticsearch for 10K+ products
228- Load only needed associations
229- Use message queue for heavy tasks
230
231## How to Use
232
233Read individual rule files for detailed explanations and code examples:
234
235```
236rules/plugin-structure.md
237rules/custom-decorator-pattern.md
238rules/perf-http-cache.md
239rules/security-input-validation.md
240rules/dal-criteria-usage.md
241```
242
243Each rule file contains:
244- Brief explanation of why it matters
245- Incorrect code example with explanation
246- Correct code example with explanation
247- Additional context and references
248
249## Full Compiled Document
250
251For the complete guide with all rules expanded: `AGENTS.md`