# Shopware Knowledge Patch > Shopware - Skill: `nevaberry/shopware-knowledge-patch-2` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add nevaberry/shopware-knowledge-patch-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/shopware-knowledge-patch-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/shopware-knowledge-patch-2 --- # Shopware Knowledge Patch ## Use this patch Load this patch for Shopware Core, plugin, app, Storefront, Administration, Store API, Admin API, deployment, or upgrade work. Open the reference that matches the affected subsystem before changing extension points, templates, configuration, API payloads, or infrastructure. ## Reference index | Reference | Topics | | --- | --- | | [platform-operations.md](references/platform-operations.md) | Runtime and dependency requirements, builds, scheduled work, queues, cache invalidation, search infrastructure, filesystems, and hosting | | [core-dal-and-extensions.md](references/core-dal-and-extensions.md) | DAL validation and queries, write events, entity definitions, custom fields, migrations, exceptions, scripts, and Core extension signatures | | [apis-and-integrations.md](references/apis-and-integrations.md) | Store API and Admin API contracts, authentication, permissions, OAuth, MCP, OpenAPI, apps, and measurement systems | | [administration.md](references/administration.md) | Administration cache hooks, Rule Builder, CMS blocks, snippets, Vue, Vite, Pinia, Meteor components, notifications, and dashboard extensions | | [storefront-and-twig.md](references/storefront-and-twig.md) | Routing, navigation, ESI pagelets, cache hashes, forms, snippets, breadcrumbs, URLs, CMS rendering, themes, accessibility, and Twig | | [commerce-orders-and-payments.md](references/commerce-orders-and-payments.md) | Orders, customers, addresses, cart rules, pricing, payment and shipping migrations, tax providers, documents, PDF, and ZUGFeRD | | [media-search-and-content.md](references/media-search-and-content.md) | Thumbnail processing, media paths, product streams, SEO resolution, and mail simulation | ## Breaking changes and removals ### Platform and build compatibility - Account for Doctrine DBAL 4, PHPUnit 11, Dompdf 3, and league/oauth2-server 9 when directly consuming those dependencies. - Administration extensions with `webpack.config.js` must migrate to `vite.config.js`, ship a 6.7-specific build, and run on native Vue 3. - Browser support follows Browserslist `defaults` unless `BROWSERSLIST` overrides it; native `URLSearchParams` replaces `query-string`. - Declare `doctrine/inflector`, `symfony/monolog-bridge`, and `symfony/proxy-manager-bridge` directly when an extension uses them. ### Store API and authentication - Stop consuming `orders.elements[].lineItems[].payload.purchasePrices`; Store API serialization removes it with no Store API replacement. - Send OAuth scopes in singular `scope` as a space-delimited string. Array-valued `scopes` is rejected, and the authorization endpoint and controller were removed without replacement. - Remove `MCP_SERVER`; MCP endpoints are available whenever `symfony/mcp-bundle` is installed, with no supported disabling flag. - Replace removed `Cached*Route` decorators. Storefront header and footer now render through their ESI routes and layout entry points. - Store API registration and login event customer entities no longer preload associations; subscribers must query related data explicitly. ### Payments and orders - Payment and shipping writes and installers must provide stable `technicalName` values; replace migration-created `temporary_` placeholders. - Extend `AbstractPaymentHandler` rather than the deprecated payment-handler interfaces. Declare refund or recurring support through `supports()`. - App payments use `manifest-3.0.xsd` and `pay-url`; asynchronous calls do not set payment states automatically, and finalize query parameters are in `requestData`. - Replace customer default-payment usage with the last-used/current method. Migrated rules use `paymentMethod`, and the changed-payment-method flow is disabled. - Use `order.primaryOrderDelivery` and `order.primaryOrderTransaction` rather than positional collection access. ### DAL and Core extensions - Replace plugin `Resources/config/entities.xml` custom entities with `EntityDefinition` or attribute entities. Declare many-to-many foreign-key fields and implement `EntityExtension::getEntityName()`. - Do not subclass DAL attribute classes, `IsFlowEventAware`, or `RuleComparison`; their inheritance contracts are closed. - Use the moved DAL `UnmappedFieldException`. When both 6.7 feature-flag states must work, catch both classes because they share no exception parent. - Replace removed Core APIs with `CreateMigrationCommand`, `MigrationQueryGenerator`, and `AccountService::loginByCredentials()` or `loginById()` where applicable. - Move cache-state constants to `CacheStateSubscriber`, and cache-cookie and invalidation-header constants to `HttpCacheKeyGenerator`. - Use `SystemConfigException` factory methods. The former system-config exception classes are replaced, while `trace()` and `getTrace()` are deprecated no-ops. ### Storefront extension points - Replace route-state variables and `.is-ctl-*` / `.is-act-*` selectors with `activeRoute`, `window.activeRoute`, and `.is-active-route-*`. - Use `addressType` instead of the deprecated address-manager Twig variable `type`. - Pass `SalesChannelContext` to `sw_breadcrumb_full` and `sw_breadcrumb_full_by_id`. - Replace `CookieProviderInterface` decorators with `CookieGroupCollectEvent` listeners; cookie Twig fields use `name` and `description`. - Resolve theme files through `ThemeFilesystemResolver`; the old theme file importer types and `StorefrontController::setTwig()` are removed. - Move header/footer data extensions to `HeaderPageletLoader` or `FooterPageletLoader` and their loaded events. - Update product-card, selector, line-item, pagination, and icon markup for the current accessibility contracts. ### Administration extension points - Register core-compatible state with `Shopware.Store.register()` and mutate it through actions. Remaining Vuex code uses the `mapVuex*` helpers. - Migrate the listed basic `sw-*` components to their `mt-*` counterparts; account for `model-value`, checked-value exceptions, renamed variants, and explicit icon sizes. - Move generic rule conditions to `sw-condition-generic` and central `rule_condition` errors instead of local condition-error mappings. - Move CMS entity-select overrides to the component-specific blocks listed in the Administration reference. - Move notification types from `Shopware\Administration` to `Shopware\Core\Framework\Notification`. ### Infrastructure and configuration - Varnish cache tags require XKeys and can no longer be stored in Redis. Replace Redis `dsn` / `url` settings with named `connection` settings. - JWT signing uses only `APP_SECRET`, which must be at least 32 characters; custom RSA secrets and the JWT-secret generation command are removed. - Declare filesystem `visibility` beside `type`, not within adapter `config`. - Run `bin/console es:index` after the Storefront Elasticsearch mapping changes. - For OpenSearch 3, omit an empty mapping `properties` member or represent it as `{}`, never `[]`. ## High-value current features ### DAL and extension authoring - Use `Criteria::excludeFields()` to omit eligible storage columns while retaining normal typed entities. Do not combine it with `addFields()`. - Put app or plugin custom-field definitions in `Resources/config/custom-fields.xml`; lifecycle operations synchronize the fields, and `include-in-search` enables product-search indexing. - Use `dal:validate --tolerate-foreign-key=constraint_name` only to tolerate a named incompatible constraint temporarily during migration. - Plugin-side DAL writes triggered by Admin API and Sync API writes execute in system scope while preserving the original context source. - `Feature::triggerDeprecationOrThrow()` accepts an optional `introducedIn` argument for a version-prefixed message. ### APIs and integrations - Scope a standard integration to the intersection with an app user's ACL by sending a valid `sw-app-user-id`; empty or invalid values are ignored. - Use the synchronous translation list, install, update, and remove Admin API actions with their matching `system:translation` privileges. - Prepare or download media through the Admin API media download actions. - Set Store API product listing, search, and search-suggest `limit` per request, subject to `shopware.api.store.max_limit`. - Refresh MCP tools when tool-list-change notifications report that a toolset's advertised availability changed. ### Storefront and content - Add non-price rule IDs through `ResolveCacheRelevantRuleIdsExtension` when `CACHE_REWORK` output varies by those rules. - Add dynamic navigation inputs through `CategoryLevelLoaderCacheKeyEvent` so cached navigation varies with extension state. - Use country-agnostic snippet names such as `en` and validate with `translation:validate`. - Use `sw_block`, `sw_source`, `sw_include`, `sw_use`, `sw_embed`, `sw_from`, and `sw_import` for complete Storefront Twig import/include forms. - Apply CMS image minimum height only in `cover` display mode. - Use `ThumbnailGeneratedEvent` for per-file thumbnail post-processing. ### Operations - Create a minimal plugin skeleton with `plugin:create --no-scaffold`. - Opt into production sourcemaps only with `GENERATE_SOURCEMAPS=true NODE_ENV=production`. - Consume the dedicated `webhook` transport when `WEBHOOKS_REWORK` is enabled; deduplicate deliveries before using the drain-to-async rollback path. - Use the delayed-cache commands or Admin API action to inspect or flush queued cache tags; force invalidation only for a critical write. - Set `SHOPWARE_SKIP_WEBINSTALLER` to a non-empty value on a read-only PaaS deployment that must bypass installer lock checks. - Lower `shopware.filesystem.batch_write_size` from its default of 250 when S3 batch operations exhaust file descriptors. ## Targeted checks - For an order re-payment flow, verify the selected method has `afterOrderEnabled`; otherwise the Store API returns HTTP 403 with `CHECKOUT__ORDER_PAYMENT_METHOD_NOT_CHANGEABLE`. - For document timestamp stability, configure the sales-channel business timezone rather than relying on an unset fallback. - For direct product-export media URL expressions, remove manual URL encoding; the body renderer already applies RFC 3986 encoding. - For custom PDF document renderers, set final bytes with `RenderedDocument::setContent()`. - For ZUGFeRD corrections, call `withDocumentInformation()` before adding deliveries, and override `getPriceWithFallback()` rather than `getPrice()`.