shopware6-best-practices

---
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
---

# 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`