Shopware-Plugins auf 6.7 migrieren: Symfony 7 und Vite

Shopware 6.7 ist kein gewöhnliches Minor-Update. Wer eigene Plugins oder Apps betreibt, steht vor einem harten technischen Schnitt: Das Framework springt auf Symfony 7.3 (Shopware Release Notes 6.7.0.0), der Administrations-Build wechselt von Webpack auf Vite (Shopware Developer Documentation), die Vue-2-Kompatibilitätsschicht ist entfernt (Shopware Release Notes 6.7.0.0) und alle Kern-Properties haben jetzt native PHP-Typen. Für Ihre Shopware-Erweiterungen heißt das: Ohne Anpassung laufen sie unter 6.7 nicht mehr sauber. Dieser Leitfaden zeigt, welche Änderungen Sie konkret treffen, wie Sie getrennte Plugin-Versionen für 6.6 und 6.7 pflegen und mit welcher Checkliste Sie die Migration systematisch angehen.

Warum 6.7 ein harter Schnitt für Erweiterungen ist

Bei früheren Sprüngen wie 6.5 auf 6.6 gab es meist eine Übergangszeit mit Deprecation-Warnungen und Kompatibilitätsschichten. Shopware 6.7 bündelt dagegen mehrere große Upgrades in einem Release und entfernt genau diese Brücken. Das Framework steht auf Symfony 7.3 (Shopware Release Notes 6.7.0.0), unterstützt werden PHP 8.2, 8.3 und 8.4 (Shopware Release Notes 6.7.0.0) - ältere PHP-Versionen fallen weg. Gleichzeitig ist die Vue-2-Kompatibilitätsschicht im Admin ersatzlos gestrichen (Shopware Release Notes 6.7.0.0). Für Erweiterungen heißt das: Der bequeme Zwischenweg fehlt, jede Baustelle muss direkt bearbeitet werden. Wer die Architektur seiner Erweiterungen kennt, kann den Aufwand realistisch einschätzen.

Symfony 7.3: Strengere Typdeklarationen im Backend

Symfony ist das Fundament unter dem Shopware-Backend. Mit dem Sprung auf Symfony 7.3 verschärfen sich die Regeln für Typdeklarationen deutlich. Symfony hat in den Versionen 6 und 7 native PHP-Rückgabetypen an nahezu alle Methoden ergänzt; fehlen diese in Ihren abgeleiteten Klassen, quittiert PHP das mit incompatible declaration-Fehlern (Symfony Upgrade Documentation). Zusätzlich entfernt jede Major-Version alle zuvor als deprecated markierten Funktionen - wer im letzten Minor 6.4 nicht aufgeräumt hat, bekommt die Quittung beim Upgrade (Symfony Upgrade Documentation).

Konkret betrifft das jede Klasse, die einen Shopware- oder Symfony-Service dekoriert, ein Interface implementiert oder eine Kernmethode überschreibt. Signaturen, die bisher ohne Parameter- und Rückgabetypen auskamen, müssen jetzt exakt zur Elternklasse passen. Das folgende Beispiel zeigt den Unterschied an einem typischen Service-Decorator:

// Bis 6.6: locker typisierte Service-Methode
public function enrich($product, $context)
{
    return $this->decorated->enrich($product, $context);
}

// Ab 6.7 / Symfony 7.3: native Typen sind Pflicht
public function enrich(
    SalesChannelProductEntity $product,
    SalesChannelContext $context
): SalesChannelProductEntity {
    return $this->decorated->enrich($product, $context);
}

• Service-Decorators: Stimmen Parameter- und Rückgabetypen exakt mit der dekorierten Klasse überein?
• Event-Subscriber: Entsprechen die Methodensignaturen den aktuellen Event-Klassen?
• Interface-Implementierungen: Sind alle nativen Rückgabetypen ergänzt, die Symfony 7 erwartet (Symfony Upgrade Documentation)?
• Deprecated-Aufrufe: Nutzen Sie noch Funktionen, die in Symfony 7.0 entfernt wurden (Symfony Upgrade Documentation)?

Native PHP-Typen an Kern-Properties

Parallel zu Symfony zieht Shopware die Typisierung im eigenen Code an: In 6.7 haben alle PHP-Klassen-Properties einen nativen Typ (Shopware Release Notes 6.7.0.0). Native Property-Typen gibt es in PHP seit Version 7.4 (PHP.net), doch der Shopware-Kern nutzte sie lange nicht flächendeckend. Wer eine Kernklasse erweitert und deren Property bisher ohne Typ übernommen oder neu deklariert hat, muss den Typ jetzt exakt angeben - sonst bricht die Klasse beim Laden.

Das Prinzip dahinter ist PHP-Standard: Typdeklarationen werden zur Laufzeit geprüft, ein unpassender Wert löst einen TypeError aus (PHP.net). Wird zusätzlich declare(strict_types=1) gesetzt, akzeptiert PHP keine automatische Typumwandlung mehr (PHP.net). Für Erweiterungen bedeutet das mehr Sorgfalt bei der Deklaration - aber auch weniger stille Fehler, weil Typkonflikte sofort sichtbar werden. Gerade für umsatzkritische E-Commerce-Funktionen ist das ein Gewinn an Stabilität.

// Bis 6.6: Property ohne nativen Typ ließ sich problemlos überschreiben
class CustomLineItem extends LineItem
{
    protected $customFields;
}

// Ab 6.7: Kern-Property hat nativen Typ -> Deklaration muss passen
class CustomLineItem extends LineItem
{
    protected ?array $customFields = null;
}

Vite statt Webpack: der Admin-Build bricht

Die sichtbarste Änderung für Admin-Erweiterungen ist der Wechsel des Build-Systems. Shopware ersetzt Webpack durch Vite (Shopware Developer Documentation). Der Grund ist pragmatisch: Der Vite-Build erzeugt den Core-Admin in rund 18 Sekunden und spart damit über 50 Prozent der bisherigen Build-Zeit (Shopware Developer Documentation). Für Sie als Erweiterungsbetreiber ist der Umstieg allerdings nicht abwärtskompatibel - eine eigene webpack.config.js wird nicht mehr gelesen.

Statt der alten Webpack-Konfiguration im build/-Verzeichnis erwartet 6.7 eine vite.config.mts direkt im src/-Verzeichnis Ihrer Administration (Shopware Developer Documentation). Webpack-Abhängigkeiten fliegen aus der package.json, Vite-Abhängigkeiten kommen hinzu. Apps sind davon nicht betroffen, weil ihr Build ohnehin vom Shopware-Kern entkoppelt ist (Shopware Developer Documentation). Details zum neuen Dev-Server haben wir im Beitrag zu Vite-Devserver und Twig-UX in 6.7.11 beschrieben.

Vue-2-Kompatibilitätsschicht entfernt

Mit 6.7 ist die Vue-2-Kompatibilitätsschicht endgültig entfernt (Shopware Release Notes 6.7.0.0). Der Admin lief seit 6.6 auf Vue 3, aber im Kompatibilitätsmodus - dieser Puffer fehlt jetzt. Komponenten, die noch auf Vue-2-Verhalten setzen, müssen auf echtes Vue 3 portiert werden. Gleichzeitig wechselt das State-Management von Vuex auf Pinia, wobei Shopware.State durch Shopware.Store ersetzt wird (Shopware Release Notes 6.7.0.0).

// Bis 6.6: Vuex-Zugriff im Admin-Modul
const product = Shopware.State.get('swProductDetail').product;

// Ab 6.7: Pinia-Store
const product = Shopware.Store.get('swProductDetail').product;

Die Umstellung betrifft vor allem Erweiterungen mit eigenen Admin-Modulen, Detailseiten oder Datengrids. Reine Storefront-Plugins ohne Administrationskomponenten sind hier deutlich weniger betroffen - für sie stehen Symfony 7.3 und die nativen PHP-Typen im Vordergrund. Wer parallel die Storefront modernisiert, kombiniert die Umstellung gern mit Techniken wie der View Transitions API für flüssige Seitenwechsel.

Weitere Breaking Changes im Überblick

Neben den vier großen Themen gibt es eine Reihe kleinerer, aber ebenso harter Änderungen, die einzelne Erweiterungen treffen. Die folgende Übersicht fasst die häufigsten Anlaufstellen zusammen (Shopware UPGRADE-6.7). Die Anpassung dieser Punkte übernehmen wir im Rahmen der individuellen Plugin-Entwicklung.

• Zahlungsart-Handler: Der neue AbstractPaymentHandler löst die bisherigen Sync- und Async-Interfaces ab (Shopware UPGRADE-6.7).
• Entity-Extensions: getEntityName() ist jetzt abstrakt und muss implementiert werden (Shopware UPGRADE-6.7).
• Scheduled Tasks: Handler erwarten einen LoggerInterface als zweites Konstruktor-Argument (Shopware UPGRADE-6.7).
• OAuth2-API: Nicht spezifikationskonforme Token-Anfragen werden nicht mehr akzeptiert; Scopes müssen als Zeichenkette übergeben werden (Shopware UPGRADE-6.7).

Getrennte Plugin-Versionen für 6.6 und 6.7

Der wichtigste praktische Rat: Versuchen Sie nicht, eine einzige Plugin-Version für 6.6 und 6.7 zu bauen. Weil der Admin-Build nicht abwärtskompatibel ist, benötigen Sie ab 6.7 ohnehin eine separate Plugin-Version mit den passenden Build-Dateien (Shopware Developer Documentation). Bewährt hat sich ein sauberer Versions-Schnitt: Der 6.6-Zweig bleibt als 1.x eingefroren und erhält nur noch Wartung, der 6.7-Zweig startet als 2.x. Als erfahrene Shopware-Agentur begleiten wir diesen Schnitt von der Planung bis zum Release.

Steuern lässt sich das über die Shopware-Kompatibilitätsangabe in der composer.json. Der eingefrorene Zweig pinnt shopware/core auf ~6.6.0, der neue Zweig auf ~6.7.0. So installiert jede Shop-Version automatisch die passende Plugin-Version:

{
    "name": "swag/example",
    "require": {
        "shopware/core": "~6.7.0"
    },
    "extra": {
        "shopware-plugin-class": "Swag\\Example\\SwagExample"
    },
    "version": "2.0.0"
}

1. 1.x-Branch auf shopware/core: ~6.6.0 festlegen und nur noch sicherheitsrelevante Fixes einspielen
2. 2.x-Branch für 6.7 abzweigen und dort Symfony-Signaturen, native Typen und den Vite-Build umsetzen
3. Admin-Komponenten von Vue-2-Mustern auf Vue 3 und Pinia portieren
4. Beide Zweige in einer CI-Pipeline gegen die jeweilige Shopware-Version testen
5. Changelog und Systemvoraussetzungen je Zweig klar dokumentieren

Wer Erweiterungen früh in zwei saubere Zweige trennt, migriert planbar statt unter Druck - und hält beide Kundengruppen lauffähig.

XICTRON Entwicklungsteam

Ihre Erweiterungen fit für Shopware 6.7 machen

Die folgende Checkliste bündelt alle Schritte, mit denen Sie eine Erweiterung sicher auf 6.7 heben. Sie eignet sich als Grundlage für die eigene Planung - oder als Leistungsumfang, den wir für Sie übernehmen. Steht parallel ein System- oder Versionswechsel an, hilft unser Shopware-Migrationsleitfaden bei der Gesamtplanung, und der Beitrag zur PHP-8.5-Migration ergänzt die Runtime-Perspektive. Nutzen Sie das Update außerdem für inhaltliche Baustellen wie barrierefreie Alt-Texte für Produktbilder.

• Alle Erweiterungen inventarisiert und nach Storefront-/Admin-Anteil sortiert
• Service-Decorators und Event-Subscriber auf native Symfony-7-Signaturen geprüft
• Erweiterte Kern-Properties mit nativen PHP-Typen versehen
• Deprecated-Aufrufe im Debug-Modus identifiziert und ersetzt
• webpack.config.js durch vite.config.mts ersetzt und sauberen Build erreicht
• Admin-Komponenten auf Vue 3 portiert, Vuex-Zugriffe auf Pinia umgestellt
• Zahlungsart-Handler auf AbstractPaymentHandler umgebaut (falls relevant)
• Getrennte 6.6- und 6.7-Zweige mit passender composer.json-Kompatibilität angelegt
• Beide Zweige in einer Staging-Umgebung end-to-end getestet
• Changelog, Systemvoraussetzungen und Rollback-Plan dokumentiert

Erfahrungsgemäß hängt der Aufwand stark vom Admin-Anteil ab: Reine Storefront-Plugins sind oft in wenigen Tagen migriert, während umfangreiche Admin-Erweiterungen mit eigenen Modulen und Datengrids mehr Zeit für die Vue-3-Portierung benötigen (Projekterfahrung). Planen Sie zusätzlich Puffer für den Test beider Zweige in einer Staging-Umgebung ein (Projekterfahrung).