PrestaShop-Modul nach einem Update defekt: die vier Ursachen

Vier Ursachenfamilien, nicht eine

Ein PrestaShop-Modul funktioniert nach einem Update nicht mehr, und das Symptom fällt jedes Mal anders aus: Im Frontend fehlt ein Block, eine Backoffice-Seite quittiert mit einem Fehler, oder die ganze Website liegt still. Dahinter steckt fast immer eine dieser vier Ursachen: ein verlorener Hook, ein kollidierender Override, eine aus dem Core entfernte Abhängigkeit oder ein inkonsistent gebliebener Cache.

Wer zuerst die richtige Familie bestimmt, spart Stunden.

Ursache 1: Der Hook ist nicht mehr registriert

Symptom: Das Modul ist aktiv, seine Konfiguration ist unversehrt, aber sein Inhalt erscheint nicht mehr.

Die Hook-Namen haben sich über die Versionen verändert. Alte Namen wie hookHeader heißen heute hookDisplayHeader, und manche Anknüpfungspunkte sind ganz verschwunden. Ein altes Modul lässt sich weiterhin installieren, zeigt aber nichts mehr an.

Prüfen Sie den tatsächlichen Stand in der Datenbank:

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';

Fehlt der erwartete Hook, registrieren Sie ihn im Backoffice über den Reiter Positionen neu oder installieren Sie das Modul erneut – nachdem Sie geprüft haben, dass die Deinstallation seine Daten nicht löscht.

Werfen Sie auch einen Blick auf ps_hook_module_exceptions: Eine Ausnahme, die einen Block auf einer bestimmten Seite ausblenden sollte, blendet ihn manchmal überall aus.

Es gibt auch den umgekehrten Fall: ein Modul, das sich nach jedem Update von selbst wieder auf einem Hook registriert, weil seine Installationsmethode erneut ausgeführt wird. Dann gehört das Modul korrigiert, nicht die Datenbank.

Ursache 2: ein kollidierender Override

Symptom: Fatal Error mit dem Hinweis auf eine bereits deklarierte Klasse, oder eine Core-Funktion, die sich widersprüchlich verhält.

PrestaShop erlaubt nur einen Override pro Klasse. Zwei Module, die Cart oder Product überschreiben, kollidieren – und das zweite gewinnt kommentarlos.

Die Datei, die man kennen muss, ist var/cache/prod/class_index.php. Sie enthält die Zuordnung jeder Klasse zu der Datei, die sie implementiert. Solange sie nicht neu erzeugt wird, greift ein hinzugefügter oder entfernter Override nicht, was zu vollkommen unverständlichen Fatal Errors führt.

Der Reflex nach jeder Änderung in override/:

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

Um zu testen, ob ein Override die Ursache ist, benennen Sie das Verzeichnis override/ vorübergehend in override_off/ um und laden neu. Kommt die Website zurück, haben Sie die Ursachenfamilie eingekreist.

Ursache 3: eine aus dem Core entfernte Abhängigkeit

Das ist seit PrestaShop 9 die dominierende Ursache und zugleich die brutalste: sofortiger Fatal Error wegen einer nicht auffindbaren Klasse.

PrestaShop 9 hat mehrere historische Bibliotheken entfernt:

• Swift Mailer, ersetzt durch Symfony Mailer;
• Guzzle, ersetzt durch den Symfony HTTP Client;
• League Tactician, ersetzt durch Symfony Messenger;
• sensio/framework-extra-bundle, ersatzlos gestrichen – damit funktionieren Routing- und Template-Annotationen nicht mehr.

Jedes Modul mit use GuzzleHttp\Client; oder use League\Tactician\...; erzeugt schon beim Laden einen Fatal Error.

Spüren Sie die betroffenen Module auf, noch bevor Sie migrieren:

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

Außerdem ist FrameworkBundleAdminController zugunsten von PrestaShopAdminController veraltet, und Admin-Controller müssen nun als Services mit Dependency Injection deklariert werden. Liefert der Backoffice-Controller eines Moduls nach dem Wechsel auf Version 9 einen Fehler 500, liegt es fast immer daran.

Schließlich läuft die Backoffice-Authentifizierung vollständig über Symfony: Module für Single Sign-on oder Zwei-Faktor-Authentifizierung, die auf dem alten Cookie aufsetzten, stellen den Dienst ein.

Ursache 4: ein inkonsistent gebliebener Cache

Symptom: sprunghaftes Verhalten, das sich von Seite zu Seite ändert oder im privaten Fenster verschwindet.

Räumen Sie nach jedem Update in dieser Reihenfolge auf:

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

Deaktivieren Sie danach unter Erweiterte Einstellungen > Leistung vorübergehend die Optionen zum Zusammenfassen und Komprimieren der Dateien, leeren Sie den Smarty-Cache und laden Sie neu. Diese Optionen bündeln die JavaScript-Dateien und legen regelmäßig Module lahm, die ihre Skripte asynchron laden.

Prüfen Sie auch die Rechte auf var/: Ein Cache, der nicht neu geschrieben werden kann, erzeugt zufällig wirkende Symptome, die sich kaum deuten lassen.

Der Weg zurück in den Betrieb

1. Den Debug-Modus aktivieren, und zwar über eine Datei config/defines_custom.inc.php mit define('_PS_MODE_DEV_', true); statt über eine Änderung an der Core-Datei. So übersteht Ihre Einstellung das nächste Update.
2. Die Logs lesen, in var/logs/ und im PHP-Fehlerprotokoll des Hosters. Der Name der fehlenden Klasse oder des nicht auffindbaren Service benennt das schuldige Modul.
3. Das verdächtige Modul in der Datenbank deaktivieren, ohne den Umweg über das möglicherweise nicht erreichbare Backoffice:

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

4. Den Cache leeren, prüfen, ob die Website zurückkommt, und dann sauber weiterarbeiten: das Modul beim Hersteller aktualisieren oder den Code korrigieren.
5. Den Debug-Modus deaktivieren, bevor Sie wieder für das Publikum öffnen.

Die nächste Runde vermeiden

Die Regel, die am meisten Zeit spart: niemals direkt in der Produktion aktualisieren. Eine Staging-Umgebung, eine schriftliche Abnahme für Bestellprozess, Zahlungen, E-Mails und Versanddienstleister sowie ein aktuelles Modulinventar genügen, um aus einem Ausfall ein Nicht-Ereignis zu machen.

Für eigens entwickelte Module beschreiben unsere Regeln für die Entwicklung eines individuellen Moduls im Detail, was ein Modul updatefest macht.

Blockiert ein Modul Ihren Shop?

Wir setzen defekte Module wieder instand und korrigieren den Code, wenn der Hersteller nicht mehr nachliefert. Siehe PrestaShop-Modulentwicklung.