Jak dodać moduły w PrestaShop

Dodawanie nowych funkcji do sklepu opartego na PrestaShop najczęściej odbywa się poprzez instalację modułów. Dzięki nim rozszerzysz płatności, integracje, marketing i wygląd bez ingerencji w kod bazowy. Poniższa instrukcja prowadzi krok po kroku przez wszystkie sposoby instalacji: z katalogu Addons, z paczki ZIP, ręcznie przez FTP oraz metodami zaawansowanymi. Zwracamy uwagę na kompatybilność, bezpieczeństwo, pracę na środowisku testowym i zarządzanie cache, a także pozycjonowanie w hooki i tryb multistore.

Przygotowanie i wymagania wstępne

Sprawdź wersję sklepu i zgodność modułu

Zanim zainstalujesz cokolwiek, ustal dokładną wersję sklepu (np. 1.6.x, 1.7.x, 8.x) i wersję PHP. W panelu administracyjnym wejdź w Zaawansowane – Informacje, aby zweryfikować środowisko. Producent modułu zwykle deklaruje, z jakimi wersjami działa. Jeśli masz PrestaShop 8, wybieraj rozszerzenia testowane pod tę gałąź. Niezgodność wersji bywa najczęstszą przyczyną białej strony, błędów 500 i konfliktów z innymi komponentami.

Wybór źródła: Addons Marketplace, dostawcy zewnętrzni, własny moduł

Najbezpieczniej korzystać z oficjalnego katalogu PrestaShop Addons, gdzie weryfikowana jest jakość i kompatybilność. Moduły od zewnętrznych firm (GitHub, prywatne repozytoria, strony producentów) instaluj po weryfikacji opinii, dokumentacji i historii wydań. Własne moduły (tworzone na zamówienie) testuj na kopii sklepu i zgodnie z wytycznymi PSR-12 oraz standardem hooków.

Uprawnienia administratora i kopia zapasowa

Do instalacji wymagane są uprawnienia SuperAdmin lub odpowiednie Role z dostępem do katalogu Moduły. Przed zmianami wykonaj kopię bazy danych i plików (pełne backupy). Jeżeli masz dostęp do panelu hostingowego, skorzystaj z migawkowych snapshotów lub zaplanuj punkt przywracania. W PrestaShop 1.7/8 rozważ użycie środowiska staging lub subdomeny testowej, aby najpierw sprawdzić instalację bez ryzyka.

Środowisko testowe i tryb debug

Włącz tryb debug tylko na środowisku testowym: Zaawansowane – Wydajność – Tryb debugowania. Pozwoli to zobaczyć pełne komunikaty błędów, stack trace i konflikty z override’ami. Na produkcji debug powinien być wyłączony, aby nie ujawniać poufnych danych oraz nie spowalniać sklepu.

Weryfikacja bezpieczeństwa i integralności plików

Sprawdź sumy kontrolne, podpisy wydawcy oraz to, czy paczka nie zawiera plików wykonywalnych poza obszarem modułu. Zwróć uwagę na uprawnienia plików po rozpakowaniu. Unikaj instalacji modułów z niesprawdzonych źródeł — to niepotrzebne ryzyko dla bezpieczeństwo i wydajności sklepu.

Instalacja z poziomu panelu administracyjnego

Instalacja z katalogu modułów/Addons w panelu

W PrestaShop 1.7/8 wejdź w Moduły i Usługi – Katalog. Wpisz nazwę funkcji (np. „płatności BLIK”) lub nazwę modułu. Przy pozycji zaufanego wydawcy kliknij Zainstaluj, a następnie Potwierdź. Jeśli moduł jest płatny i powiązany z Twoim kontem Addons, najpierw zaloguj się w panelu do konta Addons, aby powiązać licencję i pobieranie. Po instalacji pojawi się przycisk Konfiguruj — przejdź do ustawień.

Przesyłanie własnej paczki ZIP

Gdy masz gotowy plik ZIP od producenta, przejdź do Moduły i Usługi – Zarządzaj modułami – Prześlij moduł (Upload a module). Przeciągnij plik lub wybierz z dysku. System rozpakowuje paczkę, umieszcza ją w katalogu /modules i rejestruje w bazie. Po sukcesie zobaczysz komunikat o instalacji i przycisk Konfiguruj. Jeśli pojawi się błąd rozpakowywania, sprawdź limit upload_max_filesize, post_max_size i maksymalny czas wykonywania w PHP.

Wstępna konfiguracja po instalacji

Tuż po instalacji wiele modułów uruchamia kreator konfiguracji. Uzupełnij klucze API, dane logowania do usług zewnętrznych, ustawienia walut, krajów, stref podatkowych. Zweryfikuj domyślną walidację formularzy i widoczność w odpowiednich sklepach (jeśli korzystasz z kontekstu wielu sklepów). Po zapisaniu ustawień przetestuj działanie w koszyku, procesie zakupowym i na stronach, gdzie moduł coś wyświetla.

Pozwolenia, licencje i aktualizacje

Niektóre moduły wymagają połączenia z kontem Addons, by pobierać aktualizacje. W sekcji Moduły – Aktualizacje sprawdzaj dostępne wersje i dziennik zmian. Aktualizuj w oknie niskiego ruchu. Jeżeli moduł ma integrację z zewnętrzną platformą, sprawdź, czy nie wymaga akceptacji regulaminów lub whitelisting IP po stronie usługi (np. bramki płatności).

Najczęstsze problemy podczas instalacji panelowej

• Błąd 500 lub biała strona po instalacji – zwykle konflikt z innym modułem, brak kompatybilności z PHP albo nieudane migracje bazy. Włącz debug na stagingu i sprawdź logi.
• Komunikat o braku uprawnień do zapisu – katalog /modules lub /var/cache może mieć zbyt restrykcyjne prawa. Ustaw 755 na katalogach, 644 na plikach (zależnie od hostingu).
• Przerwane pobieranie – przekroczone limity PHP lub blokada firewalla. Zwiększ limity, ewentualnie zainstaluj moduł przez FTP.
• Moduł nie widoczny po instalacji – wyczyść pamięć podręczną i przebuduj assets, sprawdź aktywację pozostałych hooków.

Instalacja ręczna i zaawansowana

Instalacja przez FTP/SFTP

Skorzystaj z klienta FTP lub SFTP (zalecane). Rozpakuj paczkę modułu lokalnie. Prześlij folder modułu (nazwę techniczną, np. ps_facebook) do katalogu /modules na serwerze. Upewnij się, że struktura jest prawidłowa: /modules/nazwa_modułu/nazwa_modułu.php oraz pliki konfiguracyjne, szablony, zasoby. Po wysłaniu plików wejdź do panelu: Moduły i Usługi – Zarządzaj modułami, wyszukaj moduł i kliknij Zainstaluj. Jeśli moduł wymaga dodatkowych uprawnień, ustaw prawa do zapisu w katalogu jego zasobów (np. /modules/nazwa_modułu/views/img).

Uprawnienia plików i właściciel

Standardowo katalogi powinny mieć 755, pliki 644. Na hostingach z inną konfiguracją (FCGI/LSAPI) może być potrzebne 750/640. Najważniejsza jest zgodność właściciela plików z użytkownikiem procesu PHP, aby unikać problemów przy aktualizacjach. Nie ustawiaj 777 — to ryzyko bezpieczeństwa. Sprawdź, czy .htaccess w modułach nie nadpisuje globalnych reguł w niepożądany sposób.

Moduły wymagające Composer i budowania frontu

Coraz więcej modułów (szczególnie pod PrestaShop 8) korzysta z vendorów PHP i nowoczesnego frontendu. W takim przypadku na środowisku developerskim wykonaj composer install w katalogu modułu, a następnie npm install i npm run build (jeśli przewidziano). Zmiany przepchnij na serwer produkcyjny jako gotowy, zbudowany pakiet. Jeżeli hosting nie pozwala na Composer/NPM, poproś wydawcę o wersję z zebranymi zależnościami.

Instalacja i zarządzanie przez konsolę

W instalacjach opartych na PrestaShop 1.7/8 dostępne są polecenia bin/console (Symfony). Jeżeli środowisko je wspiera, możesz wykonać np. instalację modułu, jego włączenie lub wyłączenie. To przydaje się w automatyzacji CI/CD oraz podczas rozwiązywania problemów, gdy panel jest niedostępny. Pamiętaj, aby uruchamiać komendy w katalogu sklepu, z właściwym użytkownikiem systemu.

Wyczyszczanie cache i odświeżanie kompilacji

Po instalacji lub aktualizacji modułu wyczyść pamięć podręczną: Zaawansowane – Wydajność – Wyczyść pamięć podręczną. Jeśli korzystasz z systemów takich jak Redis, Varnish, CDN, wykonaj pełne odświeżenie. Upewnij się, że tryb „Force compilation” jest ustawiony właściwie w środowisku testowym. Często dopiero po odświeżeniu cache nowe szablony i zasoby CSS/JS zaczną się poprawnie wyświetlać.

Konfiguracja, pozycjonowanie w hookach i tłumaczenia

Odnalezienie modułu i podstawowa konfiguracja

W sekcji Moduły – Zarządzaj modułami znajdziesz wszystkie zainstalowane elementy. Użyj wyszukiwarki i filtrów (zainstalowane, nieaktywne, wymagające aktualizacji). Kliknij Konfiguruj i uzupełnij wszystkie pola: dostęp API, opcje wyglądu, mapowanie kategorii, reguły koszyka, waluty. Po każdej zmianie dokonaj testu ścieżki zakupowej w trybie incognito.

Pozycje i hooki – gdzie moduł ma działać

Wejdź w Wygląd – Pozycje i sprawdź, do jakich punktów zaczepienia przypięty jest moduł. Hooki (np. displayHeader, displayProductAdditionalInfo, displayFooter) determinują, w jakim miejscu szablonu pojawi się treść. Aby zmienić pozycję, użyj opcji Przeszczep modułu i wybierz docelowy hook. Pamiętaj, że nie każdy moduł wspiera wszystkie hooki — lista wspieranych jest w pliku głównym modułu (metoda install() i hooki zdefiniowane w klasie).

Szablony i nadpisania

Jeżeli moduł korzysta z Smarty/Twig, możesz dopasować jego wygląd. Zamiast ingerować bezpośrednio w pliki modułu, przygotuj nadpisanie w katalogu motywu (np. themes/twoj_motyw/modules/nazwa_modułu/…). Dzięki temu aktualizacje modułu nie nadpiszą Twoich zmian. Po modyfikacji szablonów pamiętaj o odświeżeniu cache i ponownym skompilowaniu zasobów.

Tłumaczenia tekstów modułu

W Międzynarodowe – Tłumaczenia wybierz tłumaczenia modułów, język i motyw. Odszukaj klucze związane z modułem, uzupełnij brakujące frazy i zapisz. Jeżeli moduł ładuje tłumaczenia dynamicznie, po zmianach wyczyść cache. Sprawdź, czy tłumaczenia nie zostały nadpisane przez aktualizację modułu; w razie potrzeby eksportuj je do plików, aby móc łatwo odtworzyć.

Konfiguracja w trybie multistore

Jeżeli używasz wielu sklepów, ustaw kontekst w prawym górnym rogu panelu. W trybie multistore każda konfiguracja może różnić się między sklepami: aktywność modułu, przypięcia do hooków, klucze API. Sprawdź, czy moduł obsługuje wielosklepowość. Jeśli nie, rozważ duplikację konfiguracji lub alternatywne rozwiązanie, które wspiera multistore natywnie.

Wydajność i wpływ na UX

Każdy moduł to dodatkowe zapytania i zasoby. Monitoruj czasy odpowiedzi (TTFB), liczbę żądań HTTP i wagę JS/CSS. Ograniczaj ładowanie na stronach, gdzie moduł nie jest potrzebny. Jeżeli moduł udostępnia lazy loading, warunkowe ładowanie skryptów lub tryb asynchroniczny — włącz je. Testuj w PageSpeed i Lighthouse, aby ocenić realny wpływ na konwersję.

Wyłączenie, odinstalowanie i czyszczenie danych

Jeśli musisz wyłączyć moduł, zrób to najpierw czasowo (Wyłącz), a dopiero potem odinstaluj. Odinstalowanie usuwa konfigurację (w zależności od modułu) i wpisy w bazie. Niektóre pozostawiają tabele lub dane raportowe — sprawdź dokumentację. Usuń nadpisania w motywie i pozostałości w /modules, jeśli deinstalator nie posprzątał wszystkiego.

Rozwiązywanie problemów i dobre praktyki

Typowe komunikaty błędów i przyczyny

• „Module cannot be loaded” — brak zgodności z wersją sklepu lub PHP, brak wymaganego rozszerzenia (np. intl, mbstring, fileinfo).
• „Zip extension not enabled” — do instalacji z paczki potrzebne jest rozszerzenie zip w PHP; włącz w php.ini lub przez panel hostingu.
• Błąd podczas aktualizacji — przerwany proces z powodu limitów czasu, zależności między modułami lub blokady plików. Rozważ aktualizację przez FTP i ręczne uruchomienie skryptów aktualizacyjnych, jeśli producent to umożliwia.
• Konflikt override — dwa moduły próbują nadpisać ten sam kontroler lub klasę. Ogranicz do jednego nadpisania lub użyj wersji zgodnej z Twoim motywem.

Diagnostyka: logi, debug i testy regresyjne

Włącz tryb debug na stagingu, przejrzyj var/logs oraz logi serwera (error_log). Sprawdź konsolę przeglądarki pod kątem błędów JS. Po instalacji nowego modułu wykonaj testy regresyjne: koszyk, rejestracja, logowanie, płatność, generowanie dokumentów (faktury), integracje ERP/WMS. Wykryte problemy reprodukuj krok po kroku, aby ułatwić zgłoszenie do wsparcia producenta.

Zgodność z wersjami PHP/MySQL i motywem

PrestaShop 8 preferuje wyższe wersje PHP niż 1.7; moduł musi być do nich dostosowany. Jeśli moduł intensywnie korzysta z bazy, zweryfikuj indeksy i zgodność typów. Upewnij się, że moduł wspiera Twój motyw — w tym nazwy hooków używane przez motyw oraz strukturę szablonów. W razie wątpliwości poproś wydawcę o listę wspieranych wersji i motywów.

Procedura rollbacku i odzyskiwanie sklepu

Przed aktualizacją zrób kopię zapasową. Gdy coś pójdzie nie tak: wyłącz moduł z poziomu bazy (ps_module – kolumna active), usuń jego wpisy w ps_hook_module, a następnie przywróć pliki i bazę z backupu. Na serwerach z dostępem do SSH możesz wycofać deploy (np. git revert). Po odzyskaniu sklepu przeanalizuj logi i plan aktualizacji w oknie mniejszego ruchu.

Lista kontrolna przed wdrożeniem na produkcję

• Spójność wersji: PrestaShop, PHP, baza, moduł.
• Backup plików i bazy, punkt przywracania.
• Test na stagingu: funkcjonalny i wydajnościowy.
• Konfiguracja licencji i kluczy API.
• Przypięcie do właściwych hooków i widoczność w kontekście sklepu.
• Wyczyszczony cache, przebudowane zasoby, odświeżony CDN.
• Plan aktualizacji i okno wdrożeniowe oraz monitorowanie po wdrożeniu.