Czym właściwie jest niestandardowy moduł i kiedy nim jest

Pod słowem „moduł” kryją się trzy różne rzeczy. Mieszanie ich kończy się źle policzonym budżetem i pretensjami po obu stronach.

PrestaShop. Moduł to katalog /modules/nazwa_modulu/ z plikiem głównym nazwa_modulu.php, w którym klasa dziedziczy po Module. Ma metody install() i uninstall(), rejestruje hooki przez registerHook() (np. displayHeader, actionCartSave, paymentOptions), a logikę frontu i panelu trzyma w kontrolerach oraz szablonach .tpl. To nie widzimisię wykonawcy — tak wygląda struktura modułu w dokumentacji PrestaShop i każdy moduł, który ma przetrwać aktualizację sklepu, musi się jej trzymać.

WordPress i WooCommerce. Wtyczka to plik z nagłówkiem Plugin Name, funkcje podpinane przez add_action() i add_filter(), opcjonalnie composer z autoloaderem, własne endpointy przez register_rest_route() i obsługa zamówień zgodna z HPOS.

Trzy kategorie rozwiązań, które trzeba rozdzielić:

• wtyczka z marketplace — płacisz za licencję i czekasz na aktualizacje dostawcy,
• konfiguracja istniejącej wtyczki — ustawienia, reguły, szablony; własnego kodu brak albo jest go kilka linii,
• kod pisany na zamówienie — ktoś bierze odpowiedzialność za kod, jego aktualizacje i rollback.

Granica jest jedna: czy logika jest unikalna dla Twojego procesu. Wycena transportu drewna (stawka za m³, strefa odległości, dopłata za rozładunek) albo rezerwacja domku (kalendarz, sezon, minimum nocy, kaucja, blokada terminu po wpłacie) to nie konfiguracja. Żadna gotowa wtyczka nie zna Twoich stawek i Twoich reguł. Jeśli po każdym zamówieniu musisz coś dopisać ręcznie w panelu, to nie kwestia wprawy pracownika, tylko brakującego fragmentu kodu.

I uczciwa deklaracja: własny moduł to nie „lepsza wtyczka”. To narzędzie do jednego przypadku. Jeśli wtyczka za kilkaset złotych i dwie godziny konfiguracji załatwia sprawę, moduł pisany 20 godzin jest stratą. Warto rozdzielić warstwę techniczną od organizacyjnej — tę drugą opisujemy szerzej w tekście o niestandardowych modułach i wtyczkach Szczebrzeszyn.

7 sygnałów, że wtyczka z katalogu przestała wystarczać

Objawy, nie odczucia. Każdy punkt da się zmierzyć albo policzyć na kartce.

• 1. Liczba aktywnych wtyczek i modułów przekracza 25–30, a czas odpowiedzi serwera rośnie. Sprawdź TTFB w PageSpeed Insights (sekcja z czasem odpowiedzi serwera) albo w Chrome DevTools: zakładka Network, kolumna „Waiting (TTFB)”. Każda wtyczka doładowuje własny CSS, JS i zapytania do bazy przy każdym odsłonie.
• 2. Konflikty po aktualizacji. Białe ekrany, ten sam hook odpalany dwa razy (np. koszt dostawy doliczony podwójnie), błąd 500 w logu PHP. To nie pech — to brak kontroli nad kodem, który nie jest Twój.
• 3. Brak endpointu API do ERP (Subiekt, Comarch). Zamówienia i stany przenosisz ręcznym eksportem CSV co tydzień. Policz: 2 godziny × 48 tygodni = 96 godzin rocznie.
• 4. Subskrypcje. Zsumuj wszystkie licencje roczne i porównaj z tym, co zapłaciłbyś raz za wdrożenie.
• 5. Wtyczka robi 80% potrzebnego zakresu, a pozostałe 20% obchodzisz ręcznie w panelu przy każdym zamówieniu.
• 6. Wsparcie nie odpowiada w 72 godziny i nie ma go po polsku. Test przed zakupem: napisz na support z konkretnym pytaniem i zmierz czas odpowiedzi.
• 7. Wtyczka nie nadąża za rdzeniem — brak zgodności z nową wersją PrestaShop, z HPOS w WooCommerce albo z PHP 8.x.

Jak to wykryć. W WordPressie w wp-config.php ustaw WP_DEBUG i WP_DEBUG_LOG na true, a WP_DEBUG_DISPLAY na false — log wyląduje w wp-content/debug.log. W PrestaShop w config/defines.inc.php włącz _PS_MODE_DEV_, dodatkowo logi znajdziesz w panelu w Advanced Parameters → Logs. Nigdy nie rób tego na produkcji — debugowanie pokazuje ścieżki i dane. Pomiar rób na staging: kopia plików i bazy, potem wyłączanie połowy wtyczek i zawężanie do winowajcy. Punktem odniesienia dla czasów są Core Web Vitals według web.dev.

Wtyczka vs moduł własny: rachunek na 3 lata

Zamień „podoba mi się / nie podoba” na arytmetykę. Policz dwa strumienie kosztów: A = (licencja roczna + godziny obejść × stawka) × liczba lat. B = godziny wdrożenia × stawka + godziny utrzymania × stawka × liczba lat. Wpisz to w jeden arkusz i porównaj.

Realne widełki godzinowe, które widzimy w projektach: prosty moduł integracyjny (dodatkowe pole w zamówieniu, eksport danych, walidacja NIP) to 12–24 h. Moduł z panelem administracyjnym i własną logiką (wycena, rezerwacje, reguły rabatowe) to 24–60 h. Integracja z ERP — stany, zamówienia, faktury — to 40–120 h, bo dochodzi uzgadnianie mapowania pól i testy na danych z magazynu.

Punkt break-even wypada zwykle między 18. a 30. miesiącem. Przesuwa się wcześniej, gdy pracy ręcznej jest powyżej czterech godzin w miesiącu, gdy sezon generuje skok zamówień albo gdy wtyczka nie obsługuje funkcji krytycznej dla sprzedaży — wtedy nie liczy się koszt, tylko czy sklep w ogóle sprzedaje.

Koszty ukryte, o których nikt nie pamięta przy wycenie: migracja danych ze starych rekordów, szkolenie pracowników (2–4 h), testy na produkcji przed sezonem (kopia bazy, zamówienia testowe, płatność w trybie sandbox) oraz utrzymanie — moduł własny nie aktualizuje się sam. Z drugiej strony masz rollback i pełną kontrolę nad tym, co dzieje się w kodzie. Jak ułożyć repozytorium, środowisko testowe i kolejność wdrożeń, opisujemy w tekście o tym, jak zorganizować pracę nad niestandardowym modułem.

Kiedy naprawdę opłaca się pisać moduł od zera

Nie każdy pomysł na funkcję w sklepie zasługuje na własny moduł. W praktyce kwalifikują projekt cztery kryteria — jeśli spełnia co najmniej dwa, własny kod ma sens. Jeśli żadne, kupujesz wtyczkę i nie dyskutujesz.

• Proces jest unikalny. Nie da się go odtworzyć ustawieniami wtyczki ani kombinacją dwóch wtyczek. Przykład: kalkulator dostawy palet, gdzie koszt zależy od strefy, wagi, liczby palet i progu załadunku.
• Nie ma gotowego rozwiązania. Najpierw sprawdzenie w katalogu PrestaShop Addons, na WordPress.org i u trzech płatnych dostawców. Jeśli istnieje wtyczka pokrywająca 80% wymagań, taniej dopiąć brakujące 20% małym modułem niż pisać całość.
• Wymagana jest integracja z zewnętrznym API. Eksport zamówień do księgowości, nadruk danych na etykiecie kurierskiej przez API przewoźnika. Gotowe wtyczki obsługują standardowe pola; gdy potrzebujesz nietypowych (numer projektu, pole własne z zamówienia), kończy się na hackach i obejściach.
• Kod będzie używany wielokrotnie — w kilku sklepach albo w jednym, ale codziennie w dużej skali. Wtedy koszt pisania się amortyzuje.

Kiedy wtyczka wygrywa bezapelacyjnie: formularz kontaktowy, meta SEO, koszyk porzucony, faktury, bramki płatności. To funkcje, których tysiące sklepów potrzebuje w identycznej formie — masz wsparcie, aktualizacje bezpieczeństwa i kogo zapytać na forum.

Osobna sprawa to sezonowość. Sklep turystyczny działający maj–wrzesień na Roztoczu płaci za licencję wtyczki przez 12 miesięcy, choć pracuje 5. Moduł własny to koszt jednorazowy — ale nie znaczy „darmowy”: po aktualizacji PrestaShop trzeba go przejrzeć i przetestować. Utrzymanie nie znika, tylko się przesuwa. Standard porządkowania kodu opisujemy w materiale o niestandardowych modułach i wtyczkach w Szczebrzeszynie.

Proces budowy modułu w 7 krokach: od briefu do produkcji

Kolejność prac jest taka sama w PrestaShop i WooCommerce — różnią się narzędzia, nie logika. Warunek: każdy krok kończy się artefaktem, który możesz pokazać osobie trzeciej. Nie ustnym „dogadaliśmy się”.

1. Brief. Cel biznesowy w jednym zdaniu („skrócić obsługę zwrotów o połowę”) plus przykładowe zamówienie: numer, produkty, waga, adres. Na tym konkretnym zamówieniu wykonawca pokazuje, że rozumie problem.
2. Specyfikacja funkcjonalna z przypadkami brzegowymi. Minimum: brak towaru na stanie, duplikat zamówienia (podwójne kliknięcie „Zapłać”), timeout API kuriera, zamówienie na 0 zł, adres zagraniczny, brak wymaganego pola. Każdy przypadek = jedno zdanie „co ma się stać”.
3. Środowisko staging. Kopia sklepu z oddzielną bazą i danymi testowymi. Wyłączone maile do klientów (inaczej wyślesz potwierdzenia z testów), płatności i kurier na piaskownicy, sklep zablokowany przed indeksowaniem.
4. Implementacja z podziałem na commity. Jedna funkcja = jeden commit, osobna gałąź na zadanie, code review przed mergem. Historia commitów to dowód, że kod nie powstał jako jeden plik na 3000 linii.
5. Testy. Scenariusze ręczne z kroku 2 plus test integracyjny API płatności lub kuriera na piaskownicy. Test bez udokumentowanego wyniku nie istnieje.
6. Wdrożenie. Poza godzinami sprzedaży (np. 2:00–4:00), kopia bazy przed zmianą, plan rollback: poprzednia wersja modułu plus przywrócenie bazy. Rollback trzeba przećwiczyć, nie tylko opisać.
7. Dokumentacja i szkolenie. README w repozytorium: co robi moduł, jakie hooki podpina, jakie tabele tworzy, gdzie trzymane są klucze API. Do tego 30–60 minut szkolenia z nagraniem dla osoby obsługującej sklep.

Sygnał ostrzegawczy: wykonawca podaje wycenę przed specyfikacją. To znaczy, że nie wie, ile pracy wymagają przypadki brzegowe. Dalsze zasady prowadzenia sklepu po wdrożeniu zebraliśmy w tekście o utrzymaniu i opiece technicznej sklepów.

Jak zapisać to w kodzie: hooki, API i bezpieczeństwo

Minimalny standard, po którym rozpoznasz dobrze napisany moduł — w obu systemach.

PrestaShop. Hooki rejestrujesz w install(): displayHeader (dołączanie CSS/JS tylko na potrzebnych stronach, nie globalnie), actionValidateOrder (zamówienie jest już zapisane, można dopiąć własną logikę), actionOrderStatusPostUpdate, displayAdminOrder. Nie nadpisuj plików core — nadpisanie ginie przy aktualizacji, a gdy dwa moduły modyfikują ten sam plik, kończy się konfliktem. Własne tabele buduj na ObjectModel, zapytania kieruj przez Db::getInstance() z parametryzacją. Pełną listę hooków znajdziesz w dokumentacji PrestaShop dla deweloperów.

WooCommerce. Własne actions i filters, kod w dedykowanej wtyczce, nie w functions.php motywu. Jeśli operujesz na zamówieniach, deklaruj kompatybilność z HPOS (High-Performance Order Storage) i używaj CRUD API — wc_get_order(), $order->get_meta() — zamiast zapytań do wp_posts i wp_postmeta.

Integracje zewnętrzne. Webhook plus kolejka plus retry, zamiast synchronicznego czekania na odpowiedź API kuriera. Przewoźnik z timeoutem 8 s to porzucony koszyk. Kolejność: zapisz zamówienie, wrzuć zadanie do kolejki (Action Scheduler, cron systemowy), wyślij z kluczem idempotencji, ponów 3 razy z odstępem 1/5/15 minut, a po niepowodzeniu oznacz zamówienie flagą do ręcznej obsługi.

Bezpieczeństwo. Walidacja i sanityzacja każdego wejścia (typ, zakres, długość), escapowanie wyjścia, zapytania parametryzowane, nonce w WooCommerce i tokeny w PrestaShop, uprawnienia pracownika do akcji w panelu. Klucze API wyłącznie po stronie serwera — w kodzie frontowym nigdy.

Log i wersjonowanie. Własny log zdarzeń modułu z poziomami info/warning/error i rotacją plików (7–30 dni), bez pełnych danych osobowych — maskuj e-mail i numer telefonu. Wersja w nagłówku pliku głównego i changelog widoczny przy aktualizacji.

8 pułapek, które psują własne moduły (i jak je wykryć przed odbiorem)

Każda z pułapek poniżej oznacza zwykle powtórne wdrożenie: 20–40 godzin pracy programisty i tydzień, w którym funkcja nie działa. Wszystkie da się wychwycić przed podpisaniem odbioru, bez czytania całego kodu.

• Hardkodowane identyfikatory kategorii, ceny i klucze API. Sprawdzenie: przeszukaj repozytorium pod kątem konkretnych wartości (grep -rn id_category modules/, grep -rn api_key). Test: na staging przenieś produkt do nowej kategorii i sprawdź, czy blok nadal działa. Wszystko, co zmienia się w czasie, ma być polem w konfiguracji modułu.
• Brak deklaracji zgodności z wersją sklepu i PHP. Moduł działa, dopóki ktoś nie kliknie aktualizacji. W PrestaShop plik główny modułu powinien zawierać $this->ps_versions_compliancy, a wtyczka WooCommerce nagłówki Requires PHP, Requires at least i WC requires at least. Brak tych wpisów przy podbiciu PHP z 8.1 na 8.3 kończy się białym ekranem.
• Brak testów przy pustym koszyku, zerowym stanie magazynowym i przekroczonym limicie API. Sprawdzenie: trzy scenariusze na staging przed odbiorem. Oczekiwany efekt to komunikat i wpis w logu, nie błąd 500.
• Brak dokumentacji i repozytorium. Po 12 miesiącach nikt nie wie, po co w kodzie jest warunek if ($qty == 0). Żądaj dostępu do Git, README z opisem konfiguracji i changelogu. Jeśli jedyną formą przekazania jest archiwum ZIP wysłane mailem, nie masz jak cofnąć wdrożenia.
• Zapytania SQL w pętli (N+1). Włącz profiler (tryb debug w PrestaShop, Query Monitor w WordPressie) i wejdź na listę z 200 produktami. Jeśli liczba zapytań rośnie razem z liczbą produktów, masz N+1 — widać to w czasie odpowiedzi, a ten przekłada się na Core Web Vitals.
• Zależność od jednej wtyczki trzeciej strony. Wyłącz ją na staging i sprawdź, czy sklep sypie błędami. Kod powinien działać warunkowo (class_exists, function_exists) i jasno komunikować brak zależności.
• Brak monitoringu. Ustal, gdzie trafiają błędy (log PHP, Sentry, skrzynka). Test: wywołaj sztuczny błąd na staging i sprawdź, czy alert dotarł w ciągu 5 minut.
• Brak timeoutu na wywołania zewnętrzne. Zablokuj ruch do API wpisem w /etc/hosts na staging i sprawdź, czy strona nadal odpowiada w mniej niż 3 sekundy.

Kolejność tych ustaleń opisaliśmy szerzej w tekście o organizacji pracy nad niestandardowymi modułami i wtyczkami.

Utrzymanie po wdrożeniu: co obejmuje opieka i jak zapisać SLA

Moduł własny to nie jednorazowy zakup. Przez trzy lata zdarzą się co najmniej dwie wymuszone aktualizacje: nowa wersja PHP i podbicie PrestaShop albo WooCommerce. Do tego dochodzą zmiany API InPost, DPD lub DHL, które potrafią wyłączyć generowanie etykiet z dnia na dzień.

W umowie serwisowej zapisz parametry, a nie ogólne zapewnienia o należytej staranności:

• Czas reakcji — np. 4 godziny w godzinach pracy, 1 dzień roboczy poza nimi.
• Czas naprawy — błąd krytyczny (sklep nie przyjmuje zamówień) do 8 godzin, błąd drobny do 5 dni roboczych.
• Kanał zgłoszeń — jeden mail i system ticketowy. Zgłoszenia na WhatsAppie są trudne do udowodnienia.
• Godziny wsparcia — np. poniedziałek–piątek, 8:00–16:00.
• Wyłączenia z gwarancji — ingerencje w kod przez inny podmiot, brak kopii zapasowych, zmiany w motywie nadpisujące szablony modułu.

Aktualizacje wymuszone rozliczaj osobno: ustal stawkę godzinową i to, kto decyduje o terminie. Aktualizację modułu poprzedzaj kopią bazy i plików oraz testem na staging — przywracanie działającego sklepu jest szybsze niż szukanie przyczyny błędu w produkcji. Zgodność wersji sprawdzaj według dokumentacji dla deweloperów PrestaShop.

Monitoring powinien obejmować nie tylko dostępność strony, ale też błędy 500, wolne odpowiedzi i nieudane webhooki. Zapisz w umowie, że pracujesz bezpośrednio z deweloperem, bez pośredników — każdy dodatkowy szczebel wydłuża czas reakcji o godziny. Zakres takich usług opisujemy w sekcji utrzymania i opieki technicznej sklepów.

Lista kontrolna: co przygotować przed zamówieniem modułu

Wykonawca, który dostaje pełny zestaw danych, wycenia trafniej i krócej testuje. Zbierz to przed pierwszym spotkaniem:

• Dokumenty i dane. Opis procesu krok po kroku (co się dzieje od dodania produktu do wysłania zamówienia), zrzuty ekranu z panelu, 3–5 przykładowych zamówień — w tym jedno z błędem, osobno dostępy do API w wersji testowej i produkcyjnej, dane do staging przekazane innym kanałem niż mailem.
• Pytania do wykonawcy. Czy dostanę środowisko staging? Czy kod trafi do repozytorium Git, do którego mam dostęp? Gdzie będzie README i changelog? Ile miesięcy gwarancji i co obejmuje? Co się stanie, gdy wtyczka trzeciej strony zniknie z rynku? Kto poprawia moduł po aktualizacji sklepu?
• Kryteria odbioru zapisane liczbami. Bez nich odbiór zamienia się w dyskusję o odczuciach. Podaj progi i narzędzia pomiaru.

Zanim wyślesz zapytanie, wróć do listy ośmiu pułapek z wcześniejszej sekcji. To gotowa checklista punktowa — wydrukuj ją i przechodź punkt po punkcie na staging, odhaczając kolejne pozycje. Pozycja bez odhaczenia oznacza, że nie odbierasz prac, a nie że „jakoś to będzie działać”.

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

Lista kontrolna do odklikania

• Repo dla każdego modułu — Sprawdź przy starcie projektu. Jeden moduł, jedno repozytorium, gałąź main dla produkcji i dev dla prac bieżących.
• Konwencja nazw — Nazwa modułu bez spacji, małymi literami, z prefiksem firmy. Weryfikuj przed pierwszym commitem — zmiana nazwy później oznacza migrację konfiguracji i danych.
• Wersja w pliku głównym — Sprawdzaj przy każdym wdrożeniu. Podbijaj numer wersji i dopisuj wpis do changelogu, żeby po miesiącach wiedzieć, co siedzi na produkcji.
• Staging z kopią bazy — Sprawdź przed pierwszym testem. Baza powinna pochodzić z ostatniej doby, żeby widzieć realne dane, a nie pusty sklep.
• Zero zmian w rdzeniu — Weryfikuj raz na kwartał, porównując pliki core z paczką instalacyjną. Wychwycisz wtedy ciche modyfikacje po poprzednim wykonawcy.
• Kopia przed wdrożeniem — Sprawdź w dniu wdrożenia. Kopia plików i bazy, zapisana poza serwerem produkcyjnym, z datą w nazwie.
• Okno wdrożenia — Ustal z wyprzedzeniem. W sklepach sezonowych (turystyka, ogrodnictwo, święta) wdrożenia planuj poza szczytem, nie w środku kampanii.
• Test akceptacyjny — Wykonaj po każdym wdrożeniu: zamówienie testowe, płatność, e-mail, etykieta kurierska, eksport do księgowości. Lista kroków powinna być zapisana, nie w głowie.
• Logi błędów na staging — Włącz tryb debug na środowisku testowym (WP_DEBUG w WordPress, tryb debug w PrestaShop) i przejrzyj logi po testach. Na produkcji debug zostaje wyłączony.
• Dokumentacja przekazania — Sprawdź przy zmianie wykonawcy. Powinna zawierać opis hooków, tabel w bazie, ustawień panelu i procedury aktualizacji.
• Kto ma dostęp — Przejrzyj raz na pół roku. Lista osób z dostępem do repozytorium i serwera powinna się zgadzać z listą osób faktycznie pracujących przy projekcie.
• Przegląd liczby wtyczek — Rób raz na kwartał. Powyżej 25–30 aktywnych wtyczek zaczyna rosnąć czas odpowiedzi serwera — mierz go w PageSpeed Insights i na staging.

Najczęściej zadawane pytania

Źródła i materiały

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