Skip to content

Shopware 6 ​

This guide covers integrating smoxy with Shopware 6. It is written for Shopware 6.7 and 6.6, the two release lines Shopware maintains as of November 2026. Where the two differ, both variants are shown.

INFO

Prerequisites: Complete the Getting Started guide first. Your shop's domain must be routed through smoxy.


Zone Settings ​

The quickest way to a correctly configured zone is the Online shop preset with the shop system Shopware, offered when you create a zone. It applies these settings:

SettingValueWhy Shopware needs it
Dynamic CacheOnCaches the storefront HTML at the edge
Respect origin Cache-ControlOnShopware marks pages that must not be shared as private and sets the edge TTL with s-maxage
Request Hostname in the cache keyOnSales channel domains on the same zone serve different pages under the same path
Cookie Value in the cache keysw-cache-hash, sw-currencyKeeps apart the cache variants Shopware creates per customer state (see below)
Strip cache-tag headersOnShopware's xkey header can grow larger than some clients accept
Conditional RuleBypass the cache for /admin, /api and /store-apiThe Administration and the APIs always need the live shop

The preset also turns on managed ignored URL parameters, stale cache and image optimization, and adds a rule that caches images by their URI only.

For a zone created without the preset, apply these settings by hand. Also keep the xkey entry in the zone's cache tag headers, which is there by default: smoxy reads the tags in Shopware's purge requests from this header.

WARNING

Why sw-cache-hash belongs in the cache key: Starting with Shopware 6.8, Shopware also caches pages for logged-in customers and filled carts. On Shopware 6.7.6 and later, the CACHE_REWORK feature flag already enables this. The only thing that tells these pages apart from the guest version is the sw-cache-hash cookie. smoxy builds its cache key from the zone settings, not from the Vary header Shopware sends. Without sw-cache-hash in the cache key, a page rendered for one customer, including that customer's prices, could be served to other visitors.


Cache Tagging (Surrogate Keys) ​

Shopware 6 tags every cacheable response with surrogate keys in the xkey header. When content changes, Shopware tells smoxy which tags to purge, so only the affected pages are cleared instead of the entire cache.

Enable Reverse Proxy Mode ​

Add the reverse proxy configuration to config/packages/shopware.yaml.

Shopware 6.7:

yaml
shopware:
    http_cache:
        reverse_proxy:
            enabled: true
            hosts: ["https://smoxy:<token>@example.com"]

Shopware 6.6:

yaml
shopware:
    http_cache:
        reverse_proxy:
            enabled: true
            hosts: ["https://smoxy:<token>@example.com"]
            use_varnish_xkey: true

Replace example.com with your shop domain and <token> with the zone's purge token.

INFO

Upgrading to Shopware 6.7: Shopware 6.7 always uses xkey tags, so use_varnish_xkey no longer has any effect. Remove it when upgrading: the option is deprecated, and Shopware 6.8 removes it entirely. The same applies to ban_method, ban_headers and purge_all.

INFO

Shopware 6.5 and older use the configuration key storefront.reverse_proxy instead of shopware.http_cache.reverse_proxy. The key changed with Shopware 6.6.0.

INFO

Cloudflare users: If you use Cloudflare, you must set up a separate subdomain for cache invalidation. See Cloudflare Setup.

Environment Variables ​

Set these variables in your shop's .env file (or .env.local):

bash
SHOPWARE_HTTP_CACHE_ENABLED=1
SYMFONY_TRUSTED_PROXIES=REMOTE_ADDR

SHOPWARE_HTTP_CACHE_ENABLED is on by default. If it is set to 0, Shopware stops marking pages as cacheable and smoxy has nothing to cache.

SYMFONY_TRUSTED_PROXIES tells Shopware to trust the X-Forwarded-For and X-Forwarded-Proto headers smoxy sends, so Shopware sees the visitor's IP address and knows the request arrived over HTTPS. REMOTE_ADDR trusts whichever address connects to Shopware directly. If a load balancer sits between smoxy and Shopware, list the addresses of that hop instead. Since Shopware 6.6, the older TRUSTED_PROXIES variable is no longer read. See Client IP at Your Origin for background.

Optimize Cache Hit Rate (Shopware 6.6 Only) ​

On Shopware 6.6, reduce cache tag fragmentation by disabling per-item tags for config, snippets, and theme config:

yaml
shopware:
    cache:
        tagging:
            each_config: false
            each_snippet: false
            each_theme_config: false

This reduces the number of tags written per page, which leads to fewer unnecessary cache invalidations and a higher cache hit rate.

WARNING

Remove this block before upgrading to Shopware 6.7. Shopware 6.7 removed these per-item tags and the shopware.cache.tagging options with them. With the block still in place, Shopware 6.7 stops with an "Unrecognized option" configuration error.


When Changes Reach smoxy ​

Shopware 6.6 sends invalidations to smoxy immediately. Shopware 6.7 delays them by default: it collects the affected tags and sends them in one batch through the scheduled task shopware.invalidate_cache, every 5 minutes by default. A change saved in the Administration can therefore take up to about five minutes to appear in the storefront. smoxy purges as soon as the request arrives.

  • Scheduled tasks must run in your setup (bin/console scheduled-task:run together with a message queue worker). Otherwise the delayed invalidations never leave Shopware.
  • Admin API requests whose changes must be visible right away can send the header sw-force-cache-invalidate: 1.
  • bin/console cache:clear:delayed sends all pending invalidations immediately.

Clearing the Entire Cache ​

To clear its whole HTTP cache, Shopware sends a BAN request without further headers to the configured host. smoxy treats this request as a Flush URL for /, so bin/console cache:clear:http and bin/console cache:clear:all only clear the start page in smoxy. Since Shopware 6.7, bin/console cache:clear no longer touches the HTTP cache at all.

To clear all cached HTML, for example as the last step of a deployment, send a Flush Content Class request to smoxy directly:

bash
curl -X BAN -H "secret: <token>" -H "type: html" https://example.com/

type: html clears all cached HTML documents and keeps images and other assets cached. The Clear Cache by Type quick action in the Hub does the same without a token. Use Flush All only when everything has to go.


Multiple Sales Channels ​

If your Shopware 6 installation uses multiple sales channels with different domains (e.g. country-specific shops), you only need to configure one domain in the reverse proxy hosts setting. Shopware knows which caches to clear for which sales channel and transmits this information to smoxy automatically.

Make sure Request Hostname is part of the zone's cache key (the Shopware preset turns it on). Otherwise the sales channels share cache entries for the same path, and a visitor of one domain could get a page of another.

WARNING

Important: All sales channels of the same Shopware installation must use the same smoxy zone.