PrestaShop-module werkt niet meer na een update

Vier families van oorzaken, niet één

Een PrestaShop-module werkt niet meer na een update, en het symptoom verschilt: een blok is uit de winkel verdwenen, een beheerpagina geeft een fout, of de hele site ligt plat. Achter die symptomen zit vrijwel altijd een van deze vier oorzaken: een verloren hook, een conflicterende override, een uit de core verwijderde dependency, of een cache die inconsistent is gebleven.

Eerst de juiste familie bepalen scheelt uren werk.

Oorzaak 1: de hook is niet meer geregistreerd

Symptoom: de module staat aan, de configuratie is intact, maar de inhoud verschijnt niet meer.

Hooknamen zijn in de loop van de versies veranderd. Oude namen als hookHeader werden hookDisplayHeader, en sommige aanhechtingspunten zijn verdwenen. Een oude module laat zich nog wel installeren, maar toont niets meer.

Controleer de werkelijke stand van zaken in de database:

SELECT h.name AS hook, m.name AS module, hm.position
FROM ps_hook_module hm
JOIN ps_hook h ON h.id_hook = hm.id_hook
JOIN ps_module m ON m.id_module = hm.id_module
WHERE m.name = 'nom_du_module';

Ontbreekt de verwachte hook, registreer die dan opnieuw via het tabblad Posities in de back-office of door de module opnieuw te installeren — nadat u hebt gecontroleerd dat de-installatie geen gegevens wist.

Kijk ook naar ps_hook_module_exceptions: een uitzondering die is toegevoegd om een blok op één specifieke pagina te verbergen, verbergt het soms overal.

Het omgekeerde bestaat ook: een module die zich na elke update vanzelf opnieuw op een hook registreert, omdat zijn installatiemethode opnieuw wordt uitgevoerd. Dan corrigeert u de module, niet de database.

Oorzaak 2: een conflicterende override

Symptoom: een fatale fout over een class die al is gedeclareerd, of onlogisch gedrag van een functie uit de core.

PrestaShop staat maar één override per class toe. Twee modules die Cart of Product overschrijven, botsen, en de tweede wint stilzwijgend.

Het bestand om te kennen is var/cache/prod/class_index.php. Daarin staat welke class door welk bestand wordt geïmplementeerd. Zolang dat bestand niet opnieuw is opgebouwd, telt een toegevoegde of verwijderde override niet mee, met onbegrijpelijke fatale fouten tot gevolg.

De standaardreflex na elke wijziging in override/:

rm -f var/cache/prod/class_index.php
rm -rf var/cache/prod/*

Wilt u testen of een override de boosdoener is, hernoem de map override/ dan tijdelijk naar override_off/ en herlaad. Komt de site terug, dan hebt u de familie van oorzaken te pakken.

Oorzaak 3: een uit de core verwijderde dependency

Dit is sinds PrestaShop 9 de dominante oorzaak, en de hardste: meteen een fatale fout op een class die niet gevonden wordt.

PrestaShop 9 heeft verschillende bibliotheken van het eerste uur verwijderd:

• Swift Mailer, vervangen door Symfony Mailer;
• Guzzle, vervangen door Symfony HTTP Client;
• League Tactician, vervangen door Symfony Messenger;
• sensio/framework-extra-bundle, geschrapt, waardoor route- en template-annotaties niet meer werken.

Elke module die use GuzzleHttp\Client; of use League\Tactician\...; declareert, geeft al bij het laden een fatale fout.

Spoor de betrokken modules op nog voordat u migreert:

grep -rl "GuzzleHttp\|League\\\\Tactician\|Swift_Mailer" modules/

Daarnaast is FrameworkBundleAdminController afgeschaft ten gunste van PrestaShopAdminController, en moeten admincontrollers voortaan als service worden gedeclareerd, met dependency injection. Een module waarvan de back-officecontroller na de overstap naar 9 een 500-fout geeft, valt vrijwel altijd onder dit punt.

Tot slot is de authenticatie van de back-office volledig op Symfony gezet: single-sign-on- of tweefactormodules die op de oude cookie leunden, houden ermee op.

Oorzaak 4: een cache die inconsistent is gebleven

Symptoom: grillig gedrag, dat per pagina verschilt of verdwijnt in een privévenster.

Ruim na elke update in deze volgorde op:

rm -rf var/cache/prod/* var/cache/dev/*

Zet daarna onder Geavanceerde instellingen > Prestaties de opties voor het combineren en comprimeren van bestanden tijdelijk uit, leeg de Smarty-cache en herlaad. Die opties voegen JavaScript-bestanden samen en breken regelmatig modules die hun scripts asynchroon laden.

Controleer ook de rechten op var/: een cache die niet kan worden herschreven, geeft willekeurige symptomen die bijzonder lastig te duiden zijn.

De methode om alles weer werkend te krijgen

1. Zet de debugmodus aan door config/defines_custom.inc.php aan te maken met define('_PS_MODE_DEV_', true);, in plaats van een bestand van de core te wijzigen. Zo blijft uw instelling na de volgende update bestaan.
2. Lees de logs in var/logs/ en in het PHP-foutenlogboek van uw hostingpartij. De naam van de ontbrekende class of de onvindbare service wijst de schuldige module aan.
3. Zet de verdachte module uit in de database, dus niet via de back-office, die onbereikbaar kan zijn:

UPDATE ps_module SET active = 0 WHERE name = 'nom_du_module';

4. Leeg de cache, controleer of de site terugkomt en pak het daarna netjes aan: de module bijwerken via de leverancier, of de code corrigeren.
5. Zet de debugmodus uit voordat u de winkel weer openstelt.

De volgende keer voorkomen

De regel die de meeste tijd bespaart: werk nooit rechtstreeks in productie bij. Een acceptatieomgeving, een uitgeschreven testplan voor het bestelproces, de betalingen, de e-mails en de vervoerders, en een actuele inventaris van uw modules zijn genoeg om een storing tot een non-event te maken.

Voor modules die speciaal voor u zijn ontwikkeld, beschrijven onze regels voor een module op maat wat een module bestand maakt tegen updates.

Blokkeert een module uw webshop?

Wij krijgen kapotte modules weer aan de praat en corrigeren de code wanneer de leverancier het laat afweten. Zie ontwikkeling van PrestaShop-modules.