PrestaShop-Modulordner: Praktischer Leitfaden für Entwickler

Ein PrestaShop-Modul ist nicht nur eine PHP-Datei mit ein paar Hooks. Ein ernsthaftes Modul hat Controller, Templates, Assets, Übersetzungen, Upgrade-Skripte, Composer-Abhängigkeiten und manchmal Service-Konfigurationen. Eine klare Ordnerstruktur macht Debugging, Updates und Support deutlich einfacher.

Die offizielle Dokumentation beschreibt die Modul-Dateistruktur. Dieser Artikel ist die praktische Ergänzung: wofür die Ordner da sind und welche Fehler häufig passieren.

Der Modulstamm

Ein Modul liegt in /modules/<module_name>/. Der Ordnername sollte klein geschrieben und vorhersehbar sein. Die Hauptdatei trägt denselben Namen: mymodule/mymodule.php. Sie registriert Hooks, Installation, Konfiguration und Metadaten.

Wenn diese Datei sehr groß wird, gehört Logik wahrscheinlich in eigene Klassen unter src/.

controllers/

controllers enthält Front- und Admin-Controller. Front-Controller liegen meist in controllers/front, Admin-Seiten in controllers/admin. Controller sollten Requests lesen, Services aufrufen, Template-Daten zuweisen und antworten. Sie sollten nicht die gesamte Geschäftslogik enthalten.

views/

views enthält Templates und Assets. Sinnvoll getrennt sind views/templates/front, views/templates/admin und views/templates/hook. CSS, JavaScript und Bilder gehören in eigene Asset-Ordner.

Diese Trennung hilft, weil dasselbe Modul in Hooks, Front-Controllern und Back-Office-Seiten sehr unterschiedlich gerendert werden kann.

src/

src ist der richtige Ort für moderne Klassen: Services, Entities, Query Builder, Validatoren, Form-Logik und externe Integrationen. Wiederverwendbare Logik gehört hierher, nicht in die Hauptdatei.

translations/

Übersetzungen sind Teil des Produkts. Labels, Fehlermeldungen, E-Mails, Hilfetexte und Front-Office-Texte brauchen einen sauberen Übersetzungsweg. Hartkodiertes Englisch lässt ein Modul schnell unfertig wirken.

upgrade/

upgrade enthält versionierte Upgrade-Skripte. Neue Tabellen, Spalten, Hooks, Tabs oder Konfigurationen gehören in Installation und Upgrade, nicht in Runtime-Checks auf jeder Anfrage.

vendor/

vendor enthält Composer-Abhängigkeiten. Diese Kopien sollten nicht manuell gepatcht werden. Wenn ein Fehler in einem gemeinsamen Paket liegt, muss das Paket selbst korrigiert und sauber synchronisiert werden.

config.xml, logo.png und override/

config.xml sollte zur Modulversion passen. logo.png ist das Back-Office-Icon. override sollte möglichst leer bleiben, denn Overrides ändern Core-Verhalten und erhöhen das Risiko bei Updates.

Grundregel

Eine gute Ordnerstruktur macht ein Modul nicht automatisch gut. Aber eine schlechte Struktur macht jeden späteren Fehler schwieriger. Klare Module sind leichter zu supporten, zu übersetzen und PrestaShop-9-kompatibel zu halten.

Praktisches Modul-Skelett

Ein sauberes Modul muss nicht kompliziert sein, aber es sollte vorhersehbar sein. Eine typische Struktur ist:

modules/
  mymodule/
    mymodule.php
    config.xml
    composer.json
    controllers/
    src/
    views/
    translations/
    upgrade/
    vendor/

Nicht jedes Modul braucht jeden Ordner. Ein kleines Hook-Modul bleibt schlanker. Ein Checkout-, SEO- oder Zahlungsmodul braucht fast immer mehr Struktur. Es geht nicht um leere Ordner, sondern um klare Zuständigkeiten.

Was in die Hauptdatei gehört

Die Hauptdatei beschreibt das Modul und verbindet es mit PrestaShop: Metadaten, Installation, Deinstallation, Hook-Registrierung und dünne Hook-Methoden. Tausende Zeilen Business-Logik, SQL in Templates oder komplexes Formularrendering gehören dort nicht hin.

Wenn diese Datei zur Ablage für alles wird, wird jeder Bug teurer. Services sind keine Mode, sondern Wartbarkeit.

controllers/ sollte dünn bleiben

Controller koordinieren Arbeit. Sie prüfen Requests, rufen Services auf, weisen Variablen zu und geben Antworten zurück. Preislogik, Sitemap-Generatoren oder Migrationen sollten nicht komplett im Controller leben.

Das ist wichtig, weil dieselbe Logik oft aus mehreren Stellen gebraucht wird: Front Controller, AJAX, Cron, Upgrade-Skript oder Hook.

src/ macht das Modul wartbar

In src/ gehören wiederverwendbare Klassen: Installer, Repositories, Validatoren, API-Clients, Services, Exporte und Importe. In PrestaShop 8 und 9 passt hier auch eine Symfony-nähere Organisation.

Faustregel: Wenn eine Klasse ohne Smarty-Template verstanden oder getestet werden kann, gehört sie wahrscheinlich in src/.

views/ ist kein Logikordner

Templates sollen Daten rendern. Präsentationsbedingungen sind okay, Datenbankabfragen und Geschäftsregeln nicht. Getrennte Ordner für Front, Admin und Hook-Templates helfen beim Debugging.

Auch Assets müssen nachvollziehbar sein. Bei einem Frontend-Problem sollte klar sein, welche Quelldatei das ausgelieferte CSS oder JS erzeugt hat.

upgrade/ gehört zum Vertrag

Module entwickeln sich. Sie fügen Spalten hinzu, registrieren Hooks, erstellen Tabs und migrieren Daten. Das gehört in Upgrade-Skripte, nicht in zufällige Runtime-Selbstheilung bei jedem Request.

vendor/ braucht Disziplin

Composer hilft, aber kopierte Vendor-Dateien direkt zu patchen ist gefährlich. Fehler in gemeinsamen Paketen gehören in die Paketquelle und müssen sauber propagiert werden.

override/ vermeiden

Overrides sind mächtig, aber update-riskant. Hooks, Controller, Services, Events oder modul-eigene Logik sind oft sicherer.

Verbindung zu den anderen Guides

Dieser Artikel behandelt den Modulordner. Für die ganze Plattform siehe den PrestaShop-Ordnerstruktur-Guide. Für Themes siehe den /themes/ Deep Dive. Zusammen decken sie Core, Theme und Modul ab.

Checkliste

• Hauptdatei bleibt lesbar.
• Controller rufen Services auf.
• Templates enthalten keine Datenbanklogik.
• Assets sind von Source bis Runtime nachvollziehbar.
• Install und Upgrade erstellen Schema, Tabs, Hooks und Konfiguration.
• Übersetzungen sind vollständig.
• Vendor-Fixes passieren upstream.
• Overrides bleiben Ausnahme.

Der in diesem Artikel sortierte Ordner ist /modules/<module_name>/.