Struktura folderów modułu PrestaShop: praktyczny przewodnik

Moduł PrestaShop to nie tylko jeden plik PHP z kilkoma hookami. Poważny moduł ma kontrolery, szablony, assety, tłumaczenia, skrypty aktualizacji, zależności Composer i czasem konfigurację usług. Gdy struktura folderów jest jasna, łatwiej debugować, aktualizować i wspierać moduł.

Oficjalna dokumentacja ma dobry opis struktury plików modułu. Ten artykuł jest wersją praktyczną: do czego służą foldery i gdzie najczęściej pojawiają się błędy.

Główny folder modułu

Moduł znajduje się w /modules/<module_name>/. Nazwa folderu powinna być mała i przewidywalna. Główny plik PHP powinien nazywać się tak samo: mymodule/mymodule.php. To on odpowiada za instalację, hooki, konfigurację i metadane.

Jeżeli główny plik robi się ogromny, logika biznesowa powinna trafić do klas w src/.

controllers/

controllers zawiera kontrolery frontowe i adminowe. Front zwykle znajduje się w controllers/front, a back office w controllers/admin. Kontroler powinien odczytać request, wywołać serwis, przypisać dane do szablonu i zwrócić odpowiedź.

views/

views zawiera szablony i assety. Warto rozdzielać views/templates/front, views/templates/admin i views/templates/hook. CSS, JavaScript i obrazy powinny mieć własne foldery.

src/

src to miejsce na nowoczesne klasy: serwisy, encje, walidatory, klienty API, helpery formularzy i logikę wielokrotnego użytku. Dzięki temu główny plik modułu pozostaje czytelny.

translations/

Tłumaczenia są częścią produktu. Etykiety, błędy, maile, teksty pomocy i komunikaty front office powinny być tłumaczalne. Twardo wpisany angielski szybko daje wrażenie niedokończonego modułu.

upgrade/

upgrade zawiera skrypty aktualizacji. Nowe tabele, kolumny, hooki, zakładki i konfiguracje powinny powstawać przy instalacji albo aktualizacji, a nie przez sprawdzanie wszystkiego przy każdym requestcie.

vendor/

vendor zawiera zależności Composer. Nie powinno się ręcznie edytować tych kopii. Jeżeli błąd jest w pakiecie współdzielonym, poprawia się źródłowy pakiet i synchronizuje go poprawnie.

config.xml i override/

config.xml powinien zgadzać się z wersją modułu. Folder override powinien być ostatecznością, bo override zmienia zachowanie core i utrudnia aktualizacje.

Zasada końcowa

Dobra struktura folderów sama nie robi dobrego modułu, ale zła struktura utrudnia każdy przyszły błąd. Czytelny moduł łatwiej wspierać, tłumaczyć, aktualizować i przygotować pod PrestaShop 9.

Praktyczny szkielet modułu

Czysty moduł nie musi być skomplikowany, ale powinien być przewidywalny:

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

Nie każdy moduł potrzebuje wszystkich folderów. Mały moduł hookowy może być prostszy. Moduł płatności, checkoutu albo SEO prawie zawsze potrzebuje większego porządku. Nie chodzi o puste katalogi, tylko o jasne odpowiedzialności.

Co powinno zostać w głównym pliku

Główny plik opisuje moduł i łączy go z PrestaShop: metadane, instalacja, odinstalowanie, rejestracja hooków i cienkie metody hooków. Nie powinien zawierać tysięcy linii logiki biznesowej, SQL-a w szablonach ani ogromnego renderowania formularzy.

Kiedy ten plik staje się magazynem wszystkiego, każdy przyszły błąd jest droższy. Serwisy to nie moda, tylko narzędzie utrzymania.

controllers/ powinien być cienki

Kontroler koordynuje pracę: waliduje request, wywołuje serwis, przypisuje zmienne i zwraca odpowiedź. Silnik cen, generator sitemap albo migracja nie powinny w całości mieszkać w kontrolerze.

Ta sama logika często jest potrzebna w kilku miejscach: front controller, AJAX, cron, upgrade albo hook. Jeśli jest uwięziona w kontrolerze, kończy się kopiowaniem.

src/ utrzymuje moduł w porządku

W src/ powinny mieszkać klasy wielokrotnego użytku: installery, repozytoria, walidatory, klienty API, serwisy, eksporty i importy. W PrestaShop 8 i 9 to też naturalne miejsce na organizację bliższą Symfony.

Prosta zasada: jeśli klasę da się zrozumieć bez szablonu Smarty, prawdopodobnie należy do src/.

views/ nie jest folderem logiki

Szablony renderują dane. Mogą mieć warunki prezentacyjne, ale nie powinny wykonywać zapytań SQL ani liczyć reguł biznesowych. Rozdzielenie front, admin i hook bardzo pomaga w debugowaniu.

Assety też powinny być możliwe do prześledzenia. Przy problemie frontendowym developer powinien wiedzieć, który plik źródłowy wygenerował CSS lub JS widoczny w runtime.

upgrade/ jest częścią kontraktu

Moduły się zmieniają: nowe kolumny, hooki, zakładki, konfiguracje i migracje danych. To powinno być w skryptach upgrade, a nie w losowym self-heal przy każdym requestcie.

vendor/ wymaga dyscypliny

Ręczne poprawianie skopiowanych plików vendor może naprawić jeden sklep na jeden dzień, ale nie jest utrzymywalne. Błąd w pakiecie współdzielonym poprawia się w źródle i propaguje do modułów.

override/ jako ostateczność

Override zmienia zachowanie core i utrudnia aktualizacje. Hooki, własne kontrolery, serwisy, eventy albo logika modułu są zwykle bezpieczniejsze.

Połączenie z innymi przewodnikami

Ten tekst dotyczy folderu modułu. Szerszy układ platformy opisuje przewodnik po strukturze folderów PrestaShop. Motywy opisuje deep dive katalogu /themes/.

Checklist

• Główny plik pozostaje czytelny.
• Kontrolery wywołują serwisy.
• Szablony nie robią SQL-a.
• Assety da się prześledzić od source do runtime.
• Install i upgrade tworzą schemat, zakładki, hooki i konfigurację.
• Tłumaczenia są kompletne.
• Vendor poprawiany jest upstream.
• Override zostaje wyjątkiem.

Folder uporządkowany w tym artykule to /modules/<module_name>/. Razem z wcześniejszymi tekstami domyka to serię: core folders, theme folders i module folders.