Shopware 6.7 ukazał się pod koniec 2024 roku jako coś, co oficjalna dokumentacja określa jako „major release with multiple breaking changes”. Dla sklepów na 6.6 migracja jest docelowo obowiązkowa, bo Shopware utrzymuje równolegle tylko najnowszą stabilną wersję i poprzednią, więc zbyt długie pozostawanie na 6.5 albo 6.6 odcina dostęp do poprawek bezpieczeństwa. Dla wtyczek tworzonych pod 6.6 kilka krytycznych API zmieniło sygnaturę albo zostało usuniętych między 6.6 a 6.7.
Ten artykuł jest bezpośrednią relacją z migracji 6.6 na 6.7, którą przeprowadziliśmy na kilku sklepach w latach 2025 i 2026, wraz z prawdziwymi pułapkami technicznymi, na jakie trafiliśmy, i łatkami, które musieliśmy wytworzyć, aby dostosować wtyczki własne i zewnętrzne. Celem jest oszczędzenie innym zespołom miesiąca debugowania, który spędziliśmy na części cichych regresji.
Co realnie zmienia się w Shopware 6.7
Poza marketingiem wydania oto zmiany w 6.7, które mają konkretny wpływ na istniejące wtyczki.
Przebudowa API Payment Handler. Interfejs AsynchronousPaymentHandlerInterface został w 6.7 usunięty. Każda wtyczka płatnicza, która implementowała go w 6.6, musi przejść na AbstractPaymentHandler. Metody pay() i finalize() mają inną sygnaturę: struktura AsyncPaymentTransactionStruct została zastąpiona przez PaymentTransactionStruct, bardziej minimalistyczną i zorientowaną na DDD.
Zmienione tagi serwisów. Tag shopware.payment.method.async, który rozróżniał płatności synchroniczne i asynchroniczne, został usunięty na rzecz ujednoliconego tagu shopware.payment.method. Jeśli Twoje pliki services.xml używały starego tagu, handler płatności przestaje się poprawnie deklarować, a metoda płatności znika z checkoutu bez żadnego widocznego błędu.
Migracja panelu z Vue 2 na Vue 3. Panel administracyjny Shopware 6.7 jest przeniesiony na Vue 3 (podczas gdy 6.6 działał na Vue 2 z warstwą zgodności). Komponenty sw-* (dawne) są stopniowo zastępowane komponentami mt-* (system projektowy Meteor). Wiele komponentów sw-* jest oznaczonych jako przestarzałe i zostanie usuniętych w kolejnym wydaniu z gałęzi 6.x. Wtyczki panelu używające komponentów sw-* muszą przejść migrację.
Zmieniony system tłumaczeń panelu. Metody $tc() (translation choice, obsługa liczby mnogiej) zostały zastąpione przez $t() z natywną obsługą liczby mnogiej. Twoje szablony panelu wywołujące {{ $tc('moja.wtyczka.label') }} muszą przejść na {{ $t('moja.wtyczka.label') }}.
Budowanie panelu przez Vite. Panel kompiluje się teraz przez Vite z plikiem manifest.json o innej strukturze niż w 6.6. Wtyczki, które wstrzykiwały swój JS panelu dawnym mechanizmem, muszą dostosować proces budowania tak, aby generował właściwy manifest, inaczej panel ładuje pusty JS zamiast Twojego kodu.
Storefront: upowszechniony Bootstrap 5.3. Przejście na Bootstrap 5.3 w storefroncie włącza natywną obsługę data-bs-theme, co upraszcza wdrożenia trybu ciemnego. Na tej konwencji opiera się nasza wtyczka DataFirefly Dark Mode. Motywy na zamówienie oparte na Bootstrapie 5.2 albo starszym mogą mieć zmienne SCSS, które przestają się mapować.
Zgodność PHP i MySQL. Wersja 6.7 wymaga PHP 8.2 lub nowszego (zalecane 8.3) oraz MySQL 8.0 lub nowszego albo MariaDB 11.4 LTS. Hostingi wciąż działające na MySQL 5.7 albo MariaDB 10.x muszą zmigrować bazę przed aktualizacją aplikacji.
Breaking changes wtyczka po wtyczce, na które trafiliśmy
Na migrowanych przez nas sklepach oto konkretne błędy odkryte przy przejściu z 6.6 na 6.7.
Wtyczka płatnicza Worldline. W wersji na 6.6 implementowała AsynchronousPaymentHandlerInterface. Przy przejściu na 6.7 wtyczka przestaje się poprawnie ładować, a metody płatności Worldline znikają z checkoutu. Łatka wymaga migracji na AbstractPaymentHandler i przepisania metod pay() oraz finalize() z nową sygnaturą PaymentTransactionStruct. Szacowana praca: od 2 do 4 dni dla doświadczonego dewelopera Shopware.
Własne wtyczki panelu z komponentami sw-*. W naszych wtyczkach kilka własnych komponentów panelu używało sw-card, sw-button, sw-text-field i podobnych. W 6.7 te komponenty jeszcze istnieją, ale są oznaczone jako przestarzałe. Zastępują je mt-card, mt-button i mt-text-field. Migracja jest mechaniczna, ale wymaga wyczerpującego przeglądu wszystkich plików panelu.
Snippety i tłumaczenia. Pliki snippetów w 6.6 używały czasem struktury z liczbą mnogą konsumowanej przez $tc(). W 6.7 z $t() część struktur snippetów nie działa identycznie. Do systematycznego przetestowania, zwłaszcza przy snippetach z licznikami („1 produkt”, „N produktów”).
Custom field klienta i synchronizacja. Nasza wtyczka Dark Mode dla Shopware przechowuje preferencję użytkownika w custom fieldzie df_dark_mode_preference na encji klienta. Migracja do 6.7 zachowała zgodność custom fields, ale API synchronizacji ma nieco inną sygnaturę. Do systematycznego przetestowania po aktualizacji.
Wymagany OpenSearch 2.19 lub nowszy. Jeśli Twój sklep korzysta z wyszukiwania pełnotekstowego przez OpenSearch (dawniej Elasticsearch we wcześniejszych wersjach Shopware), 6.7 wymaga minimum OpenSearch 2.19. Wersje 1.x nie są już wspierane. Migrację klastra OpenSearch trzeba przewidzieć przed aktualizacją aplikacji.
Lista kontrolna migracji w 8 krokach
Aby migracja z 6.6 na 6.7 przebiegła pod kontrolą, oto kolejność, którą stosujemy wewnętrznie.
Krok 1: audyt zainstalowanych wtyczek. Wypisz wszystkie aktywne wtyczki. Dla każdej sprawdź w sklepie z rozszerzeniami albo na GitHubie, czy istnieje wersja zgodna z 6.7. Wtyczki bez aktualizacji to poważne ryzyko: do tymczasowego wyłączenia, do załatania we własnym zakresie albo do zastąpienia.
Krok 2: audyt motywu na zamówienie. Jeśli używasz własnego motywu, a nie natywnego Storefront, sprawdź zgodność z Bootstrapem 5.3, zmiany struktury bazowego layoutu oraz system Vite w panelu, jeśli motyw wstrzykuje własny JS do panelu.
Krok 3: aktualizacja infrastruktury. PHP 8.2 lub nowszy, MySQL 8 albo MariaDB 11.4 LTS, OpenSearch 2.19 lub nowszy, jeśli używany, oraz świeży Node.js (18 lub 20 LTS). Do wykonania przed aktualizacją samego Shopware.
Krok 4: pełna kopia zapasowa. Baza danych plus katalog plików plus zawartość config/. To krok, który bywa zaniedbywany aż do chwili, gdy aktualizacja nieodwracalnie coś zepsuje. Wykonywać systematycznie przed każdą zmianą.
Krok 5: migracja na środowisku staging. Sklonuj produkcję na identyczne środowisko przedprodukcyjne, wykonaj tam aktualizację do 6.7 i wyczerpująco zwaliduj, zanim ruszysz produkcję. To nie jest opcja: na migrowanych przez nas sklepach 30 % miało krytyczne błędy wykryte wyłącznie na stagingu.
Krok 6: aktualizacja aplikacji Shopware. Przez menedżera aktualizacji w CLI: bin/console system:update:prepare, a następnie bin/console system:update:finish. Warto dokładnie przeczytać oficjalną dokumentację co do opcji (skip-asset-build i inne). Licz od 30 minut do 2 godzin zależnie od wielkości bazy.
Krok 7: rekompilacja motywu i panelu. Po aktualizacji rdzenia zrekompiluj motyw (bin/console theme:compile) i przebuduj panel (bin/build-administration.sh). W Shopware 6.7 panel kompiluje się przez Vite, więc historyczna komenda theme:compile już nie wystarcza dla panelu.
Krok 8: wyczerpujące testy po aktualizacji. Pełna ścieżka: nawigacja po katalogu, karta produktu, dodanie do koszyka, checkout, płatność (każda metoda testowana osobno), panel klienta, panel administracyjny (każdy zainstalowany moduł). W sklepach B2B przetestuj także oferty, konta hierarchiczne i ceny per klient.
Ciche pułapki, na które trafiliśmy naprawdę
Poza udokumentowanymi breaking changes oto subtelne błędy, których nie widać zaraz po aktualizacji.
Handler płatności, który się nie deklaruje. Jak wspomniano wyżej, wtyczka płatnicza ze starym tagiem shopware.payment.method.async nie rejestruje się już w 6.7. Metoda płatności znika z checkoutu, ale nie jest zgłaszany żaden błąd, bo odpowiadające payment_method_id nadal istnieje w bazie, tylko handler nie jest instancjonowany. Objaw po stronie klienta: metoda widnieje w panelu (konfiguracja, kanały sprzedaży, metody płatności), ale nie pojawia się w checkoucie.
Własny komponent panelu renderujący się pusto. Komponent, który używał $tc() bez powiązanego tłumaczenia (przypadek etykiet zapisanych na sztywno), nie renderuje w 6.7 niczego. Brak błędu w konsoli, po prostu pusty placeholder. Do wykrycia ręcznym przeglądem własnych ekranów panelu po aktualizacji.
Manifest Vite, który się nie generuje. Jeśli Twoja wtyczka panelu była w 6.6 budowana własnym skryptem (bezpośrednio webpack albo rollup), taki build może nie wygenerować pliku manifest.json oczekiwanego przez Shopware 6.7. Objaw: panel się ładuje, ale JS Twojej wtyczki nie jest wykonywany. Rozwiązanie: dostosować build tak, aby eksportował manifest zgodny z Vite.
Snippety z liczbą mnogą, które przestają się tłumaczyć. Jeśli miałeś snippety ze strukturą typu {count} | jedna rzecz | {count} rzeczy konsumowaną przez $tc(), przejście na $t() wymaga innej składni. Niezmigrowane snippety wyświetlają surowy szablon zamiast tłumaczenia.
Custom field, którego nie ma już w API. Kilka modyfikacji API warstwy dostępu do danych (DAL) w 6.7 zmieniło serializację części złożonych custom fields (multi-select, JSON). Wartości nadal istnieją w bazie, ale są odczytywane inaczej. Do przetestowania na krytycznych custom fieldach.
Podsumowanie: migracja konieczna, ale wymagająca wyprzedzenia
Migracja Shopware z 6.6 na 6.7 nie jest zwykłą pomniejszą aktualizacją. Wprowadza istotne breaking changes wymagające realnej pracy nad wtyczkami (zwłaszcza płatniczymi), własnym panelem i infrastrukturą. Sklepy, które robią tę migrację w jeden dzień, „bo przecież tylko kliknęliśmy Aktualizuj”, odkrywają błędy na produkcji kilka tygodni później, czasem z bezpośrednim wpływem na obrót (zepsuta płatność, bezużyteczny panel).
Realistyczny nakład czasu dla sklepu z 5 do 10 wtyczkami zewnętrznymi i własnym motywem to od 5 do 15 osobodni doświadczonego dewelopera Shopware plus kilka dni odbioru. Wyprzedzenie tematu, aktualizacja na stagingu i wyczerpujące testy przed produkcją odróżniają migrację kontrolowaną od migracji w kryzysie.
Po pokrewne tematy techniczne przejrzyj kategorie Aktualności e-commerce oraz Wydajność i Core Web Vitals. A jeśli szukasz dobrze utrzymywanych wtyczek Shopware 6.7 stawiających na wydajność, nasza wtyczka Dark Mode jest zgodna z Shopware 6.7 od dnia premiery i pokazuje wzorce techniczne dopasowane do nowej architektury (anti-FOUC, custom field klienta, zdarzenia JS do synchronizacji z komponentami zewnętrznymi).
Przeczytaj także: PrestaShop 9 kontra PrestaShop 8.
