Czym jest PrestaShop module generator i do czego służy?

PrestaShop module generator to narzędzie, które na podstawie kilku danych wejściowych — nazwy modułu, wersji PrestaShop, listy hooków i informacji o autorze — tworzy gotowy szkielet modułu. Efektem jest paczka ZIP z plikiem głównym (np. mojmodul.php), klasą dziedziczącą po Module, metodami install() i uninstall(), pustymi szablonami oraz — jeśli zaznaczysz taką opcję — prostym panelem konfiguracji w zapleczu. Generator nie wymyśla funkcji, którą moduł ma realizować. To szkielet, nie produkt.

W praktyce spotkasz trzy typy generatorów:

• Generator online — formularz w przeglądarce. Najszybszy start, zero instalacji, ale zwykle generuje kod pod jedną wersję PrestaShop i nie aktualizuje się razem z nim.
• Generator CLI — uruchamiany z terminala, często jako skrypt społecznościowy. Wygodny w powtarzalnych projektach, ale sprawdź datę ostatniego commita: narzędzie porzucone dwa lata temu wygeneruje kod bez wsparcia dla PrestaShop 8.
• Boilerplate z GitHuba — publiczne repozytorium ze szkieletem. Nie generuje niczego dynamicznie, po prostu kopiujesz strukturę i podmieniasz nazwy. Najbardziej przewidywalne rozwiązanie dla agencji.

Dla kogo to jest. Początkujący deweloper nauczy się na szkieletcie konwencji PrestaShop: nazewnictwa plików, rejestracji hooków, struktury kontrolerów. Agencja skróci czas do pierwszego commita z godzin do minut. Właściciel sklepu zamawiający moduł zrozumie, co realnie dostaje w pierwszym etapie i dlaczego wycena nie kończy się na wygenerowanej paczce.

Czego generator nie zrobi. Nie napisze logiki biznesowej (np. własnego algorytmu rabatowego czy mapowania danych z ERP), nie zintegruje płatności ani kurierów, nie doda testów, nie przeprowadzi Cię przez aktualizacje pod kolejne wersje PrestaShop i nie przejmie utrzymania. Te elementy to nadal praca dewelopera — dlatego warto najpierw uporządkować wybór i wdrożenie modułów PrestaShop, a dopiero potem pisać własny.

Jak działa generator modułów PrestaShop — od formularza do paczki ZIP

Proces jest krótki: wypełniasz formularz, dostajesz ZIP. Warto wiedzieć, co dokładnie ląduje w paczce, żeby nie zgubić się przy pierwszej modyfikacji.

Wejście. Typowy generator prosi o: nazwę modułu, autora, wersję PrestaShop (1.7 lub 8.x), listę hooków oraz przełącznik odpowiedzialny za panel konfiguracji. Część narzędzi pozwala też wybrać, czy chcesz kontroler frontowy, adminowy, czy oba.

Wyjście. W katalogu /modules/mojmodul/ znajdziesz plik główny z klasą dziedziczącą po Module:

class Mojmodul extends Module
{
    public function __construct()
    {
        $this->name = 'mojmodul';
        $this->version = '1.0.0';
        $this->author = 'Twoja firma';
        $this->ps_versions_compliancy = ['min' => '1.7.0.0', 'max' => _PS_VERSION_];
        parent::__construct();
    }

    public function install()
    {
        return parent::install()
            && $this->registerHook('displayHeader')
            && $this->registerHook('displayHome')
            && $this->registerHook('actionCartSave');
    }
}

Metoda uninstall() wygląda analogicznie, ale pamiętaj o usunięciu własnych wpisów z tabeli configuration — inaczej po reinstalacji zostaną stare ustawienia. Pełny opis konwencji znajdziesz w oficjalnej dokumentacji dla deweloperów PrestaShop.

config.xml to metadane modułu: nazwa, wersja, autor, zgodność wersji i lista hooków. PrestaShop czyta go przy instalacji i przy walidacji. Jeśli podbijesz wersję w kodzie, a zapomnisz o XML, dostaniesz rozjazd. logo.png (32×32 px) to ikona na liście modułów — bez niej wyświetla się domyślna grafika, co u klienta wygląda na niedokończoną pracę. Tłumaczenia trzymaj w katalogu translations/; w PrestaShop 8 to pliki XLIFF generowane z panelu Międzynarodowe > Tłumaczenia, starsze moduły używają plików PHP. W szablonach używaj {l s='Tekst' mod='mojmodul'} — bez mod= string trafi do słownika core, nie modułu.

Krok po kroku: generujesz moduł PrestaShop w 15 minut

Załóż, że masz działający lokalny PrestaShop i chcesz zobaczyć efekt bez ryzyka dla sklepu klienta.

1. Środowisko. PHP 8.1 lub nowsze, MySQL 5.7+/8.0, PrestaShop 8.x na localhost (Laragon, XAMPP albo Docker). Włącz tryb dev: define('_PS_MODE_DEV_', true) w config/defines.inc.php, potem wyczyść cache — Parametry zaawansowane > Wydajność > Wyczyść pamięć podręczną lub usuń zawartość var/cache.
2. Nazwa modułu. Wpisz mojmodul: małe litery, bez spacji, myślników i polskich znaków. Nazwa modułu, katalogu i klasy muszą być identyczne — inaczej PrestaShop go nie rozpozna.
3. Hooki. Zaznacz displayHeader (dołączenie CSS/JS), displayHome (blok na stronie głównej) i actionCartSave (reakcja na zmiany w koszyku). Włącz panel konfiguracji, jeśli moduł ma mieć ustawienia.
4. Paczka ZIP. Pobierz plik i wgraj go przez Moduły > Menedżer modułów > Wgraj moduł albo rozpakuj do /modules/mojmodul/. Uprawnienia: 644 dla plików, 755 dla katalogów, właściciel taki sam jak proces PHP.
5. Instalacja. Znajdź moduł na liście i kliknij Zainstaluj. Sprawdź, czy nie pojawiły się ostrzeżenia o zgodności wersji.
6. Pierwszy test. Dodaj produkt do koszyka (sprawdza actionCartSave), wejdź na stronę główną (displayHome), a w źródle strony poszukaj plików CSS/JS modułu (displayHeader). W trybie dev błędy PHP zobaczysz od razu na ekranie.

Pułapka, która kosztuje najwięcej. actionCartSave odpala się przy każdym zapisie koszyka, także przy zmianie ilości. Jeśli wstawisz tam odwołanie do zewnętrznego API, każde kliknięcie plusa przy produkcie generuje żądanie sieciowe. Przy 200 aktywnych koszykach w godzinie szczytu zablokujesz sklep. Trzymaj tam możliwie lekką logikę, a cięższe operacje przenieś do kolejki lub zadania cron.

Zanim wdrożysz moduł na produkcję, przećwicz cały scenariusz na kopii sklepu — usługi PrestaShop dla sklepów w praktyce zaczynają się od stagingu, nie od wgrania paczki na żywy serwer.

Anatomia wygenerowanego modułu: pliki, hooki i panel administracyjny

Wygenerowany szkielet to katalog modules/mojmodul/ z plikiem głównym mojmodul.php i klasą Mojmodul extends Module. Nazwa klasy to nazwa modułu w CamelCase, nazwa katalogu — małymi literami: minimum 3 znaki, tylko litery, cyfry i podkreślenia, bez myślników i bez cyfry na początku. Złamiesz konwencję — instalator odrzuci moduł, zanim cokolwiek się uruchomi.

W __construct() ustawiasz metadane, od których zależy całe życie modułu: name, version, author, ps_versions_compliancy (zakres min–max), kategorię w panelu (tab) i bootstrap = true, jeśli chcesz korzystać z komponentów PrestaShop w widokach. install() wykonuje się raz: rejestruje hooki przez registerHook(), tworzy tabele z prefiksem _DB_PREFIX_ i zapisuje wartości domyślne przez Configuration::updateValue(). uninstall() jest jego lustrem i musi sprzątać dokładnie to samo.

Hooki mają sztywną konwencję nazw: hookDisplayHeader(), hookDisplayHome(), hookActionCartSave(). Metoda musi być publiczna, a hook zarejestrowany — inaczej PrestaShop nigdy jej nie wywoła. Kontrolery frontowe leżą w controllers/front/, dziedziczą po ModuleFrontController, a link generujesz przez getModuleLink(). Kontrolery administracyjne (ModuleAdminController) obsługują listy, filtry i formularze w back office. Widoki to Twig w views/templates/front/, hook/ i admin/. Teksty wyciągaj do domen tłumaczeń, np. Modules.Mojmodul.Shop, pliki trzymaj w translations/.

Własną logikę — ERP, płatności, eksport — trzymaj poza plikiem głównym: klasa modułu ma tylko spinać hooki z serwisami. Od 1.7 możesz w module uruchomić Composer i autoloadować klasy z src/. Wtedy zmiana logiki nie rozjeżdża instalatora. Zobacz też nasz materiał o tym, jak wybierać i wdrażać moduły PrestaShop.

Najczęstsze błędy po użyciu generatora i jak je wykryć

Generator nie zna Twojego sklepu, więc produkuje szkielet, który działa przy pierwszym uruchomieniu i sypie się przy pierwszej aktualizacji, jeśli nie poprawisz pięciu rzeczy.

• uninstall() to nie formalność. Jeśli install() tworzy tabele i zapisuje konfigurację, uninstall() musi je usunąć: DROP TABLE, Configuration::deleteByName(), unregisterHook(), usunięcie zakładki w panelu. Objaw zaniedbania: druga instalacja wywala się na CREATE TABLE, w bazie zostają tabele z prefiksem sklepu, a w panelu wisi martwa zakładka. Test: odinstaluj moduł na stagingu i przeszukaj bazę po fragmencie nazwy.
• Walidacja i escapowanie. Tools::getValue() zwraca surowy ciąg z żądania. Wstawiony do zapytania daje SQL injection, wypisany w szablonie daje XSS — a XSS w panelu administratora pozwala przejąć sesję. Stosuj castowanie ((int)), Validate::isInt(), Validate::isEmail(), a w zapytaniach pSQL() dla stringów. W Twig nie używaj |raw na danych użytkownika, w Smarty pisz |escape:'htmlall':'UTF-8'.
• Wersje. Moduł z operatorami z PHP 8 wywali fatal error na serwerze z PHP 7.4. ps_versions_compliancy ma odzwierciedlać realnie przetestowane wersje, nie życzenia. Wymagania PHP dla konkretnego wydania PrestaShop sprawdzisz w dokumentacji dla deweloperów PrestaShop.
• Token CSRF. Formularz w back office bez weryfikacji tokena można wysłać z obcej strony i podmienić np. klucz API w konfiguracji. Każda akcja zmieniająca stan musi iść metodą POST i przechodzić przez kontrolę tokena.
• Cache i hooki. Zmieniasz szablon i nic — bo Smarty trzyma skompilowane pliki w var/cache/. W trybie deweloperskim włącz wymuszanie kompilacji, po wdrożeniu wyczyść cache raz, celowo. Hook nie działa też, gdy nie jest zarejestrowany albo szablon nie wywołuje {hook h='displayX'} — weryfikujesz to w zakładce Pozycje.

Gorzej, gdy moduł gada z zewnętrznym systemem — wtedy walidacja po obu stronach jest warunkiem koniecznym. Więcej o tym w tekście o integracji modułu z PrestaShop API.

Bezpieczeństwo i zgodność z PrestaShop 1.7/8 oraz marketplace

Standardy sprowadzają się do trzech poziomów: dane, dostęp, dystrybucja.

Dane. Walidacja po stronie serwera jest obowiązkowa — atrybut required w HTML to tylko wygoda dla użytkownika. W kontrolerze administracyjnym zbieraj komunikaty do tablicy $this->errors i nie zapisuj nic, dopóki jest niepusta. W Twig escapowanie HTML jest domyślnie włączone, ale tracisz je przy |raw i w blokach literal; w Smarty pamiętaj o |escape:'htmlall':'UTF-8'. Dane wstawiane do skryptu escapuj w kontekście JS, a wstawiane do adresu — w kontekście URL. To trzy różne mechanizmy, nie jeden.

Dostęp. Token CSRF: kontrolery administracyjne mają wbudowaną weryfikację, formularze frontowe potrzebują własnego pola ukrytego sprawdzanego przy każdej akcji zmieniającej stan. Uprawnienia plików: 644 dla plików, 755 dla katalogów, właściciel to użytkownik, spod którego działa PHP — nie root. Katalogu nie ustawiaj na 777, bo to otwarte drzwi do wstrzyknięcia kodu. Klucze API trzymaj poza katalogiem publicznym, a jeśli muszą leżeć w module, dołóż blokadę dostępu i nie nadpisuj zabezpieczeń, które PrestaShop sam wstawia w kluczowych katalogach.

Dystrybucja. PrestaShop Addons sprawdza deklarowaną kompatybilność, licencję, obecność tłumaczeń i brak błędów z walidatora. Teksty wpisane na sztywno w szablonach to niemal pewny problem — używaj domen i plików w translations/. Biblioteki osób trzecich: dołącz ich licencje i nie usuwaj nagłówków. Aktualną checklistę i opis wymagań znajdziesz w dokumentacji deweloperskiej PrestaShop. Przed publikacją przejdź pełny test na kopii sklepu — tak samo jak przy każdym wdrożeniu i migracji PrestaShop.

Generator, gotowy moduł czy moduł na zamówienie? Porównanie kosztów i czasu

Nie ma jednej dobrej odpowiedzi. Są trzy drogi i każda ma inny próg wejścia oraz inne ryzyko po stronie sklepu.

Generator plus Twoja praca. Szkielet powstaje w 0–2 godziny. Ale generator nie napisze logiki: mapowania pól z ERP, obsługi webhooków płatności, reguł rabatowych czy zapisu do własnych tabel. Realnie 20–80 godzin pracy dewelopera, zależnie od liczby hooków i integracji. Rozliczasz stawkę godzinową, więc koszt rośnie razem z zakresem. Zaleta: kod jest Twój i można go dowolnie rozwijać. Wada: nie ma gwarancji, że ktoś go później utrzyma.

Gotowy moduł z marketplace. Instalacja to 30 minut do 2 godzin, jeśli funkcja jest standardowa. Płacisz za licencję, często też za roczny abonament na aktualizacje. Ryzyko: konflikt z dodatkami, które już masz — dwa moduły nadpisujące ten sam hook potrafią wyłączyć koszyk albo podmienić cennik. Przed zakupem sprawdź zgodność z Twoją wersją PrestaShop i wersją PHP, a nie tylko z opisem na stronie sprzedawcy.

Moduł na zamówienie. Wycena wychodzi z liczby godzin, typowo 20–80 h dla średniego zakresu. Przy integracji z ERP, płatnościami i kurierami to często 80–200 h plus testy i dokumentacja. Dostajesz kod dopasowany do procesów i kogoś, kto odpowiada za wdrożenie.

Praktyczna podpowiedź: policz godziny, zanim wybierzesz. Jeśli szkielet ma obsłużyć jeden dodatkowy przycisk w panelu, wystarczy generator. Jeśli moduł ma wysyłać stany magazynowe do ERP co 15 minut, to projekt wdrożeniowy. Sposób wyboru i wdrażania rozszerzeń opisujemy szerzej w materiale o modułach PrestaShop, a sam generator najlepiej poznać z oficjalnej dokumentacji dla deweloperów PrestaShop.

Checklista wdrożenia modułu po generatorze — od stagingu do produkcji

Po wygenerowaniu szkieletu najważniejsza jest dyscyplina wdrożeniowa. Kolejność poniżej oszczędza godziny nerwów i chroni dane klientów.

• Backup przed instalacją. Dump bazy (mysqldump albo eksport z panelu), kopia katalogu /modules, /themes oraz pliku app/config/parameters.php. Zrób próbne przywrócenie na osobnym środowisku — backup, którego nie odtworzyłeś, nie jest backupem.
• Staging 1:1. Te same wersje PrestaShop, PHP i MariaDB oraz ten sam szablon. Włącz tryb deweloperski: w pliku config/defines.inc.php ustaw _PS_MODE_DEV_ na true, potem wyczyść cache w Parametry zaawansowane, Wydajność. Bez tego błędy znikają za białym ekranem.
• Logi. Sprawdzaj katalog var/logs (osobno dev i prod), error_log PHP oraz logi serwera www. Ostrzeżenia o przestarzałych funkcjach to zapowiedź awarii po podniesieniu wersji PHP.
• Test funkcjonalny. Instalacja, konfiguracja, każdy hook na froncie, panel, koszyk, zamówienie testowe do statusu zakończonego, faktura i mail. Osobny przebieg dla multistore, jeśli masz więcej niż jeden sklep.
• Aktualizacja i odinstalowanie. Wgraj nowszą wersję modułu i sprawdź migracje. Potem odinstaluj i zobacz w bazie, czy tabele oraz wpisy w tabeli configuration zostały usunięte. Śmieciowy wiersz w configuration potrafi zepsuć konfigurację po ponownej instalacji.
• Dokumentacja. Zapisz wersje PrestaShop, PHP i MySQL, listę hooków, zależności (cURL, rozszerzenia PHP), pliki nadpisywane przez override oraz autora i datę wdrożenia.

Na produkcję wchodzisz dopiero po zamknięciu wszystkich punktów: wyłączasz tryb dev, włączasz cache, instalujesz moduł przez panel i robisz jedno zamówienie kontrolne po wdrożeniu.

Kiedy PrestaShop module generator to zły wybór?

Generator robi szkielet. Są projekty, w których lepiej od razu zamówić usługę wdrożeniową, bo sam szkielet tylko odsuwa problem w czasie.

• Integracje z ERP, płatnościami i kurierami. Tu nie chodzi o jeden plik. Trzeba obsłużyć autoryzację, mapowanie pól, ponowienia przy błędach, logi i zgodność kwot. Płatności: statusy przelewów, zwroty, płatności częściowe. Kurierzy: etykiety, listy przewozowe, statusy przesyłek, gabaryty i waga. Każda z tych rzeczy to osobne scenariusze błędów, które ktoś musi zaprojektować i przetestować na stagingu.
• Wielosklepowość, wydajność, SLA. Przy id_shop i id_shop_group konfiguracja per sklep, ceny, stany i szablony potrafią się rozjechać. Do tego cache, indeksy w bazie i czas odpowiedzi przy katalogu liczącym tysiące produktów. Jeśli potrzebujesz umowy z czasem reakcji i monitoringu, generator tego nie zapewni — potrzebny jest zespół i ustalony zakres wsparcia.
• Brak osoby, która dokończy i utrzyma kod. To najczęstsza pułapka. Szkielet wygląda dobrze, ale nikt w firmie nie umie dopisać hooka ani poprawić błędu po kolejnej aktualizacji PrestaShop. Kod zostaje na serwerze i blokuje aktualizacje, bo nikt nie chce ryzykować.

W takich przypadkach sensowniej zacząć od rozmowy o zakresie niż od generatora. Zobacz, jak prowadzimy wdrożenia i migracje PrestaShop oraz jakie usługi PrestaShop realizujemy. Prosty test decyzyjny: jeśli nie potrafisz w jednym zdaniu powiedzieć, kto dokończy moduł i kto go zaktualizuje po premierze nowej wersji sklepu, to nie jest projekt na generator.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Środowisko staging z kopią bazy i plików — Przed jakąkolwiek instalacją na produkcji. Kopia bazy pozwala bezpiecznie testować uninstall() i migracje.
• Instalacja modułu na staging — Wgraj ZIP do /modules/ i zainstaluj przez panel. Sprawdź, czy instalacja kończy się bez błędów i komunikatów w logach.
• Test hooków na froncie — Wywołaj każdy zadeklarowany hook (np. displayHeader, displayHome, actionCartSave) i sprawdź efekt na stronie oraz w koszyku.
• Test panelu konfiguracji — Zapisz ustawienia, odśwież stronę i sprawdź, czy wartości się utrzymują po ponownym wejściu.
• Test odinstalowania i czystości bazy — Odinstaluj moduł na kopii bazy i sprawdź, czy nie zostały tabele ani wpisy w ps_configuration.
• Walidacja wejścia i escapowanie wyjścia — Testuj złośliwymi ciągami znaków w każdym polu formularza, także w panelu administracyjnym.
• Token CSRF w każdej akcji zapisującej — Sprawdź formularze i wywołania AJAX — bez tokena akcja jest podatna na wywołanie z zewnątrz.
• Zgodność wersji PHP i PrestaShop — Porównaj wersje stagingu i produkcji oraz deklarację ps_versions_compliancy w pliku głównym modułu.
• Tłumaczenia i brak tekstów na sztywno — Sprawdź, czy wszystkie komunikaty przechodzą przez system tłumaczeń i czy pliki językowe są kompletne.
• Wpływ na wydajność — Zmierz czas odpowiedzi strony przed i po włączeniu modułu oraz liczbę dodatkowych zapytań do bazy.
• Uprawnienia plików 644/755 — Zweryfikuj po wgraniu paczki na serwer produkcyjny, nie tylko lokalnie.
• Kopia zapasowa przed wdrożeniem — Pliki i baza — zanim cokolwiek wgraniesz na produkcję, miej punkt powrotu.
• Wdrożenie w oknie serwisowym — Włącz tryb maintenance na czas instalacji i testów na produkcji, żeby nie łapać błędów na żywym ruchu.
• Monitoring po wdrożeniu — Pierwsze 24–48 godzin: logi serwera, logi PHP, działanie koszyka i zamówień.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• Google Ads – dokumentacja API