Błąd modułu Magento po aktualizacji do 2.4.7? Naprawa

Dlaczego moduł wysypał się akurat po przejściu na Magento 2.4.7?

Moduł przestał działać w Magento 2.4.7 najczęściej z trzech powodów: restrykcyjnej obsługi typów w PHP 8.3 (i 8.2), wymuszenia nagłówków Content Security Policy (CSP) na checkoutcie oraz aktualizacji TinyMCE 4 do wersji 6. Gdy zewnętrzny kod operuje na dynamicznych właściwościach klas lub korzysta z usuniętych z rdzenia metod, sklep natychmiast wyrzuca błąd 500 albo wywala kompilację DI. Nawet stabilne komercyjne moduly Magento 2 od czołowych dostawców potrafią polec na zmianach wprowadzonych przez Adobe Commerce w tej gałęzi.

Wersja 2.4.7 to nie jest kosmetyczny patch bezpieczeństwa. Wprowadza ona ponad 140 poprawek bezpieczeństwa, ale przede wszystkim wymusza pełną zgodność z PHP 8.3. Jeśli moduł był pisany pod PHP 7.4 lub 8.1 i autor nie zadeklarował jawnie pól w klasach (tzw. dynamic properties, które w PHP 8.2 wyrzucają Deprecated, a w 8.3 w połączeniu z restrykcyjnym error handlerem Magento potrafią przerwać wykonanie skryptu), cały proces renderowania strony leży.

Kolejnym winowajcą jest aktualizacja bibliotek JavaScript. Magento 2.4.7 odcina stare adaptery jQuery UI i podbija zależności frontendowe. Jeśli moduł Amasty, Mirasvit czy MageWorx modyfikował panel administracyjny lub koszyk za pomocą przestarzałych widgetów, po aktualizacji dostaniesz w konsoli błąd TypeError: $(...).widgetName is not a function, a przycisk zapisu po prostu przestanie reagować.

Jak zdiagnozować, który moduł blokuje setup:di:compile i checkout?

Zamiast zgadywać, uruchom proces kompilacji w trybie deweloperskim i przejrzyj surowe logi systemowe. Najbardziej bezwzględnym narzędziem weryfikacji jest komenda Dependency Injection:

bin/magento setup:di:compile

Jeśli kompilacja wywala się z komunikatem typu Fatal error: Declaration of Vendor\Module\... must be compatible with..., masz czarno na białym, która klasa gryzie się z nowymi sygnaturami typów w Magento 2.4.7. Najczęstsze scenariusze błędów w logach to:

• Błędy unii typów (Union Types) i typów zwrotnych: Rdzeń Magento 2.4.7 doprecyzował zwracane typy w dziesiątkach interfejsów (np. public function execute(): ResultInterface). Jeśli moduł nadpisuje metodę pluginem typu around lub dziedziczy po klasie bazowej bez wskazanego typu, kompilator natychmiast zatrzyma pracę.
• Restrykcyjne CSP w var/log/csp_whitelist.log: W wersji 2.4.7 Magento domyślnie włączyło restrykcje CSP dla stron składania zamówienia. Jeśli Twoja bramka płatności (np. skrypt iframe PayU, Przelewy24 czy widżet ratalny) nie ma zdefiniowanego pliku etc/csp_whitelist.xml, przeglądarka zablokuje połączenie z serwerem płatności, a klient zobaczy puste okno.
• Nieobsługiwany OpenSearch 2.12+: Wiele modułów filtrujących i wyszukiwarek (np. starsze wersje Smile ElasticSuite czy Sphinx) próbuje wysyłać zapytania w składni nieobsługiwanej przez nowsze silniki wyszukiwania. W efekcie listingi kategorii zwracają kod 500.

Szybki test izolacji problematycznego rozszerzenia wykonasz z poziomu CLI, wyłączając podejrzany moduł bez usuwania danych:

bin/magento module:disable Vendor_BrokenModule
bin/magento setup:upgrade
bin/magento cache:flush

Co najczęściej psuje się w polskich integracjach: InPost, ERP i bramki płatności?

U nas w projektach widzimy powtarzający się schemat: po aktualizacji silnika sklepu międzynarodowe moduły zazwyczaj mają gotowy patch od vendorów w 48 godzin, podczas gdy lokalne wtyczki dedykowane na rynek polski potrafią leżeć tygodniami.

1. Wtyczki kurierskie (InPost Geowidget, Paczkomaty)

Integracje InPostu często opierają się na ładowaniu zewnętrznego skryptu mapy Geowidget. W Magento 2.4.7 blokuje go albo CSP, albo konflikt w RequireJS spowodowany zmianami w asynchronicznym ładowaniu skryptów checkoutu. Efekt? Klient wybiera Paczkomat, ale mapa się nie renderuje, a formularz nie zapisuje identyfikatora punktu odbioru w quote_address.

2. Konektory ERP (Comarch ERP Optima, Subiekt GT / nexo)

Większość polskich integratorów ERP przesyła dane za pośrednictwem customowych endpointów REST API lub bezpośrednich zapytań bazodanowych. W Magento 2.4.7 zaostrzono walidację schematów webapi.xml oraz autoryzację tokenów Bearer. Dodatkowo parsery XML w starych modułach gubią się na serializacji danych w PHP 8.3, co prowadzi do zrywania synchronizacji stanów magazynowych i cen. W krytycznych momentach zamówienia wpadają do bazy sklepu, ale nie tworzą dokumentów ZK/FS w Subiekcie.

3. Płatności BLIK i bramki Przelewy24 / PayU

Zmiany w architekturze obsługi sesji checkoutu potrafią zerwać przekazywanie parametrów transakcji do formatki BLIK. Jeżeli moduł płatności próbuje korzystać z przestarzałych sesji Magento\Checkout\Model\Session w sposób bezpośredni w kontrolerach webhooków zamiast dedykowanych repozytoriów, transakcja po stronie banku zostaje rozliczona, ale zamówienie w Magento pozostaje ze statusem Pending Payment.

4. Fakturowanie, KSeF i JPK

Moduły generujące dokumenty PDF oraz przygotowujące dane pod Krajowy System e-Faktur często korzystają ze starych bibliotek pokroju mPDF czy dompdf w wersjach niekompatybilnych z PHP 8.3. Każda próba wygenerowania faktury po stronie panelu admina kończy się krytycznym błędem pamięci lub błędem parsowania stylów CSS.

Ile realnie kosztuje naprawa modułu, a kiedy taniej kupić nową licencję?

Gdy moduł odmawia posłuszeństwa, stajesz przed prostym dylematem biznesowym: płacić za roboczogodziny software house’u czy odnowić subskrypcję u twórcy modułu. Poniższa tabela przedstawia realne koszty rynkowe w polskich realiach:

Jeśli moduł pochodzi od dużej stajni, najczęściej najtańszym ruchem jest wykupienie support access, pobranie paczki kompatybilnej z 2.4.7 i podbicie wersji przez Composera. Jeśli jednak w kodzie modułu były robione customowe modyfikacje przez poprzednich wykonawców, prosta aktualizacja nadpisze zmiany i unieruchomi kluczowe procesy w sklepie.

Jak krok po kroku naprawić moduł bez zatrzymywania sprzedaży?

W SISL zawsze powtarzamy jedną zasadę: nigdy nie naprawiamy modułów bezpośrednio na serwerze produkcyjnym (na tzw. żywym organizmie). Aby przywrócić sprawność sklepu, zastosuj sprawdzoną procedurę:

1. Zbuduj środowisko stagingowe 1:1: Skopiuj bazę i pliki na osobną instancję z identyczną konfiguracją PHP 8.3, OpenSearch 2.x oraz Redis.
2. Zidentyfikuj błędy typowania i dynamic properties: Włącz pełne raportowanie błędów w app/etc/env.php (tryb developer) i przejdź całą ścieżkę zakupową od dodania do koszyka, przez wybór metody dostawy, po symulację webhooka płatności.
3. Przygotuj patch przez Composera: Zamiast modyfikować pliki w katalogu vendor/, użyj narzędzia cweagans/composer-patches. Pozwala to nałożyć poprawki zgodności z PHP 8.3 w bezpieczny, powtarzalny sposób, który nie zniknie przy kolejnym uruchomieniu composer install.
4. Uzupełnij polityki CSP: Dodaj domenę zewnętrznego API lub zasobu do pliku etc/csp_whitelist.xml Twojego motywu lub modułu potomnego:

<?xml version="1.0"?>
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
    <policies>
        <policy id="script-src">
            <values>
                <value id="inpost-geowidget" type="host">https://geowidget.inpost.pl</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>

5. Przeprowadź deployment zerowego przestoju (Zero-Downtime Deploy): Wdrażaj zmiany z poziomu potoku CI/CD lub przełączając symlinki wygenerowanych katalogów pub/static oraz generated/code.

Jeśli po aktualizacji do Magento 2.4.7 Twój koszyk nie działa, zamówienia nie spływają do ERP, a wdrożony software house rozkłada ręce — napisz do nas. Przeanalizujemy logi, wskażemy wąskie gardła i doprowadzimy sklep do pełnej stabilności bez konieczności kosztownego cofania całej wersji systemu.