Shopware 6.6 to 6.7 Migration Guide - Breaking Changes and a Safe Upgrade Path

A while back I was midway through upgrading a client's Shopware store to 6.7 when the admin simply refused to load — no error page, no useful console output, just a blank screen. Two hours later I'd traced it to a plugin that had published a "6.7 compatible" release but hadn't actually rebuilt its assets against Vite. The vendor had bumped the constraint in composer.json and called it done. That afternoon taught me more about 6.7's breaking changes than any changelog ever could.

Shopware 6.7 landed in June 2025 and ships meaningful architectural jumps: Vite everywhere, Symfony 7.4, Vuex out / Pinia in, and a redesigned cache invalidation model. None of these are insurmountable, but each one can silently kill a plugin or break a theme if you upgrade blind. This guide walks you through every breaking area, with concrete before/after code, so you can ship 6.7 without a production incident.

Should You Upgrade Right Now?

My honest take: probably not immediately. Shopware 6.6 is an LTS release — it receives security patches for roughly two years from its GA date. There is no urgency. The correct move is a deliberate, staged upgrade, not a panic migration chasing the newest minor.

Upgrade when:

• Your third-party plugins already have 6.7-compatible releases
• You have a staging environment that mirrors production
• You have capacity to QA checkout, custom storefront areas, and admin workflows end-to-end

If you are on 6.6 and none of your plugins have published 6.7 builds yet, wait. Plugin incompatibility is the single biggest cause of upgrade outages — I've seen it enough times to make it my first check, every single time.

Step 0: Run the Upgrade Check Before Touching Anything

My rule before any major Shopware upgrade: don't touch composer.json until you've run the official compatibility scanner:

shopware-cli project upgrade-check

This scans your install against the 6.7 compatibility matrix and prints exactly what breaks — deprecated usages, incompatible plugin versions, missing technicalName entries, and more. Treat its output as your checklist. Everything below maps to findings this tool surfaces. I can't count the number of times this single command has saved me from a nasty surprise on staging.

Vite Replaces Webpack — and Plugins Are Always What Bite First

The most impactful frontend change: both the admin and storefront build pipelines switched from Webpack to Vite. The two pipelines are not backwards compatible. A plugin compiled against 6.6's Webpack setup will not load in 6.7.

This is the part that burned me in the story above. Any plugin shipping admin Vue components or custom Storefront JS must publish a separate release targeting 6.7. If the plugin vendor hasn't done this yet, the plugin is either broken or blocked from loading entirely. A bumped version constraint without a rebuilt asset bundle is not a compatible release — verify the changelog carefully.

What this means for your project:

• Audit every installed plugin in composer.json. Check the vendor's changelog for a "6.7 / Vite" release.
• If you maintain internal plugins, update their build config to Vite and publish a new version before upgrading the shop.
• Custom themes extending the default Storefront may need their Webpack-specific configs removed.

For safe, upgrade-resilient theme overrides, see the Shopware decoration best practices — patterns like template extensions and SCSS variable overrides tend to survive major version jumps better than deep JS patches.

Symfony 7.4 — Type Declarations and the Death of Request::get()

All Symfony packages are updated to v7.4, and Doctrine DBAL moves to v4. Symfony 7 tightened method signatures and removed APIs that were deprecated for years. In my experience, the most common plugin break is a service that extends or implements a Symfony class whose method signature changed.

Check your phpstan.neon / phpcs baseline for any extends or implements on Symfony core classes. The upgrade-check tool flags these; resolve them before bumping the composer constraint.

Request::get() is Gone — Use Explicit Bags

This one catches people off guard. Symfony deprecated the magic Request::get() helper, which searched attributes → query → request bags in sequence. In 6.7 you must be explicit:

Before (6.6):

$foo = $request->get('foo');

After (6.7) — explicit bag:

// Query string (?foo=bar)
$foo = $request->query->get('foo');

// POST body
$foo = $request->request->get('foo');

// Route attribute
$foo = $request->attributes->get('foo');

After (6.7) — when the source is genuinely unknown (rare):

use Shopware\Core\Framework\Routing\RequestParamHelper;

$foo = RequestParamHelper::get($request, 'foo');

Prefer explicit bags wherever possible. RequestParamHelper is a compatibility bridge for legacy code paths, not a blanket replacement. I've found that forcing yourself to be explicit here actually surfaces assumptions in the original code that were never intentional.

Redis Requirement

If your setup uses Redis: the php-redis extension must be v6.1 or higher — this is a hard Symfony 7.4 constraint. Check before upgrade:

php -r "echo phpversion('redis');"

Anything below 6.1 needs an extension update first. I keep this check in my pre-upgrade notes now after catching it too late once on a client environment.

Admin JS — Vuex Out, Pinia In

The Shopware admin moved fully out of Vue 3 compatibility mode and migrated state management from Vuex to Pinia. The old Vuex helper utilities still exist but are renamed to avoid collision:

Rename every import and usage in your admin components. A project-wide search for mapState\|mapMutations\|mapGetters\|mapActions catches them all. Honestly this rename is mechanical and quick — don't let it intimidate you.

vue-i18n was also updated to v10, which removes the tc function. The $tc shorthand on Vue components still works (it internally calls t), but any direct tc(...) calls in non-component JS need to be replaced with t(...).

Storefront HTML — Semantic Elements and Pagelet Loaders

Several previously <div>-based list areas are now proper <ul>/<li> elements:

• Account order overview
• Cart line-items

If your custom theme targets these with element selectors (e.g. .cart-item-list > div), update to > li. It's a quick find-and-replace but I've seen it slip through code review and make it to staging, where a customer notices the broken styling before anyone else does.

More importantly: header, footer, payment methods, and shipping methods are no longer loaded by GenericPageLoader. If you have a custom page type that relied on GenericPageLoader pulling these in automatically, you must now extend HeaderPageletLoader and FooterPageletLoader explicitly.

Additionally, ErrorTemplateStruct had its header/footer properties, getters, and setters removed. Custom error pages extending this struct need to fetch header/footer independently.

Payment & Shipping — technicalName Is Now Non-Nullable

Both payment_method and shipping_method tables have their technical_name column made non-nullable. Any payment or shipping method created without a technicalName in the API will now fail validation.

Before (worked in 6.6, fails in 6.7):

$paymentMethod = [
    'name' => 'My Custom Payment',
    'handlerIdentifier' => MyPaymentHandler::class,
];

After (6.7):

$paymentMethod = [
    'name' => 'My Custom Payment',
    'technicalName' => 'payment_my_custom', // required, lowercase snake_case
    'handlerIdentifier' => MyPaymentHandler::class,
];

Run the upgrade-check tool — it will flag payment/shipping entries in your database that are missing this value so you can backfill before upgrading. Don't skip this step; a missing technicalName will surface at the worst possible moment otherwise.

Delayed Cache Invalidation and the ESI Gotcha

Cache invalidation in 6.7 is delayed by default: the cache is no longer purged immediately on data change, but at regular intervals. This is a deliberate performance trade-off — it reduces invalidation storms at the cost of slight staleness windows.

More critically: ESI (Edge Side Includes) must be explicitly enabled at the HTTP layer, or your header and footer will not render. This one cost me an afternoon once — everything looked fine in a shallow smoke test, but navigating deeper into the storefront revealed that the header was just... gone. ESI is how Shopware assembles cached page fragments, and 6.7 requires the layer in front of PHP (Symfony HttpCache, Nginx, or Varnish) to support and process <esi:include> tags.

If you are running Symfony's built-in HttpCache (the default for many deployments), ensure esi: true is set in your framework config:

# config/packages/framework.yaml
framework:
    esi: true
    fragments: true

For Nginx / Varnish setups, consult your reverse-proxy documentation for ESI processing configuration. If this is skipped, page rendering works but header/footer fragments are missing — an infuriatingly subtle bug that won't show up until you actually click around the storefront.

For a deeper look at how Shopware's HTTP cache layer works and how to tune it, the Shopware 6 performance guide covers cache configuration in detail.

My Upgrade Checklist

Run through this in order on a staging branch before touching production:

• ☐ shopware-cli project upgrade-check — resolve every reported item
• ☐ Verify all plugins have 6.7-compatible (Vite) releases; update or disable the rest
• ☐ Update internal plugins' build config to Vite
• ☐ Rename Vuex helper imports → mapVuexState etc. in admin components
• ☐ Replace $request->get() with explicit bags or RequestParamHelper
• ☐ Check php-redis version ≥ 6.1 if Redis is in use
• ☐ Audit theme CSS for div → ul/li element selector breakage
• ☐ Update custom page types to extend HeaderPageletLoader/FooterPageletLoader
• ☐ Backfill technicalName on all payment and shipping methods
• ☐ Enable ESI in Symfony/Nginx/Varnish config
• ☐ Full QA: checkout flow, account pages, cart, admin order management

For build-time catches, a solid CI pipeline with PHP static analysis pays dividends here — see quality tools that matter for tool recommendations that surface these classes of error before they hit staging.

The authoritative list of every breaking change is in UPGRADE-6.7.md in the shopware/shopware GitHub repo. If anything in this guide contradicts that file, the file wins.

Worth It? Absolutely — Just Don't Rush It

Shopware 6.7 is a genuinely better platform — Vite is faster, Pinia is cleaner, and the delayed cache model scales better under load. I've done this migration on a few stores now and every time the result is noticeably snappier admin builds and a less tangled state management story. The upgrade is not particularly hard if you approach it methodically: run the compatibility scanner, fix plugins first, work through the backend changes, then validate the storefront and cache layer.

If you have a complex plugin ecosystem or a heavily customized Shopware installation and want someone to plan and execute the migration without a production outage, that's exactly the kind of work I take on. Reach out and we can scope it together.

Useful References

• Shopware 6.7 UPGRADE notes (GitHub) — the canonical breaking-change list
• Shopware developer docs — plugin development and API reference
• Symfony 7.0 upgrade guide — covers the Symfony-side breaking changes in depth
• Shopware CLI docs — project upgrade-check and other migration utilities
• Vite migration guide — Vite API changes relevant to plugin build configs