Ein Update eines Shopware-Projekts von 6.5 auf 6.6 ist mehr als ein gewöhnliches Composer Update. Shopware 6.6 erhöht die Systemvoraussetzungen und bringt Änderungen mit, die Entry Points des Projekts, Storefront JavaScript Plugins, Erweiterungen, Themes und die Serverkonfiguration betreffen können.

Dieser Leitfaden verbindet den offiziellen Update-Ablauf von Shopware mit Lösungen für Fehler, die mir bei Updates realer Projekte begegnet sind.

Vor dem Update von Shopware 6.5 auf 6.6

Starte nicht direkt mit composer update auf dem Produktivsystem. Bereite zuerst das Projekt und einen zuverlässigen Wiederherstellungsweg vor:

Shopware empfiehlt das Update über Composer, weil diese Methode stabiler ist und Timeouts im Browser vermeidet.

Offizieller Shopware Guide: Update von 6.5 auf 6.6

Der empfohlene Composer-Ablauf

Führe zunächst im Hauptverzeichnis des Projekts den Vorbereitungsbefehl aus:

bin/console system:update:prepare

Passe danach die Shopware-Package-Constraints in der composer.json an die gewünschte 6.6-Version an. Die Versionen von shopware/core, shopware/administration, shopware/storefront, shopware/elasticsearch und weiteren Shopware-Paketen müssen zusammenpassen.

Löse und installiere anschließend die neuen Abhängigkeiten:

composer update

Wenn Composer erfolgreich abgeschlossen wurde, führe die Datenbankmigrationen aus und schließe das Systemupdate ab:

bin/console system:update:finish

Aktualisiere zum Schluss die Symfony-Recipe-Konfigurationsdateien:

composer recipes:update

Dieser Befehl wird leicht übersehen, gehört aber zum von Shopware dokumentierten Composer-Update-Ablauf. Prüfe die daraus entstehenden Konfigurationsänderungen sorgfältig, bevor du sie commitest oder deployest – insbesondere, wenn das Projekt eigene Symfony-Konfiguration enthält.

Offizielle Shopware Dokumentation: Shopware über Composer aktualisieren

1. Fehler „Class Shopware\Core\HttpKernel not found“ beheben

Das Update kann bereits am Anfang mit folgender Meldung abbrechen:

Uncaught Error: Class "Shopware\Core\HttpKernel" not found

In diesem Fall enthalten die Entry-Point-Dateien des Projekts meistens noch Code aus der älteren Shopware-Version. Vergleiche und aktualisiere die folgenden Dateien mit der exakten Shopware-6.6-Version, die du installieren möchtest:

Für ein Update auf Shopware 6.6.0.2 findest du die passenden Dateien im Tag 6.6.0.2:

Shopware 6.6.0.2 public/index.php

Shopware 6.6.0.2 bin/console

Shopware 6.6.0.2 bin/shopware

Übernimm Dateien nicht ungeprüft aus einer anderen Patch-Version. Nachdem die Entry Points korrigiert wurden, kannst du mit dem oben beschriebenen Composer-Ablauf fortfahren.

2. Nicht mehr funktionierende JavaScript Plugins reparieren

Nach dem Core Update kann eigenes Storefront JavaScript ausfallen, obwohl Administration und Storefront weiterhin laden. In Shopware 6.6 sollten eigene Plugins asynchron registriert werden. Öffne die main.js deines Themes oder deiner Erweiterung und ersetze den direkten Import durch einen dynamischen Import.

Vorher:

import ExamplePlugin from './plugins/example.plugin';
window.PluginManager.register('Example', ExamplePlugin, '[data-example]');

Nachher:

window.PluginManager.register(
    'Example',
    () => import('./plugins/example.plugin'),
    '[data-example]',
);

Dieselbe Änderung gilt, wenn ein bestehendes Plugin überschrieben wird.

Vorher:

import MyListingExtensionPlugin from './plugin-extensions/listing/my-listing-extension.plugin';
window.PluginManager.override(
    'Listing',
    MyListingExtensionPlugin,
    '[data-listing]',
);

Nachher:

window.PluginManager.override(
    'Listing',
    () => import('./plugin-extensions/listing/my-listing-extension.plugin'),
    '[data-listing]',
);

Shopware 6.6 Upgrade Guide: JavaScript Plugins asynchron registrieren

3. PHP-Versionsfehler in Composer beheben

Composer kann die Dependency Resolution mit einer dieser Meldungen abbrechen:

Your Composer dependencies require a PHP version *
shopware/administration v6.6.1.0 requires php ~8.2.0 || ~8.3.0
Your php version (8.1.27) does not satisfy that requirement.

Prüfe zunächst die PHP-Version der Kommandozeile:

php -v

Sowohl die PHP-Version der Kommandozeile als auch die vom Webserver verwendete Version müssen die Anforderungen von Shopware 6.6 erfüllen. Auf Servern mit mehreren PHP-Installationen können diese Versionen voneinander abweichen.

Für Shopware 6.6.1.0 kannst du den PHP Constraint im require-Bereich der composer.json entsprechend anpassen:

"php": "~8.2.0 || ~8.3.0"

Ändere den Composer Constraint nicht nur, um die Fehlermeldung zu unterdrücken. Aktualisiere zuerst die tatsächlich verwendete PHP Runtime und führe Composer anschließend mit derselben unterstützten Version aus.

4. Fehler beim Erstellen eines Medienordners beheben

Nach dem Update kann das Erstellen eines Medienordners mit folgender Meldung fehlschlagen:

CRITICAL: Uncaught Error: assert($levelField instanceof TreeLevelField)

Prüfe, welche php.ini aktiv ist, und deaktiviere die Auswertung von Assertions in der Produktivumgebung:

; don't evaluate assert()
zend.assertions=-1

Starte nach der Änderung den zuständigen PHP-FPM- oder Webserver-Dienst neu, leere den Shopware Cache und versuche den Vorgang erneut.

Shopware Dokumentation: PHP-Konfiguration optimieren

Nach dem Update

Bevor du das aktualisierte Projekt auf Production deployest:

Falls das Update weiterhin fehlschlägt, sichere die vollständige Composer- oder Shopware-Fehlermeldung. Die erste Exception im Log ist meistens hilfreicher als die letzte allgemeine Fehlermeldung im Browser.

Unterstützung beim Shopware Update anfragen