Dokumentacja PrestaShop to nie jedna strona — mapa źródeł

Fraza „prestashop dokumentacja” nie prowadzi do jednego miejsca. W praktyce to cztery zasoby i każdy odpowiada na inny typ pytania. Szukanie hooka w dokumentacji użytkownika kończy się kwadransem straconym i zerowym wynikiem — i odwrotnie.

Rozdziel je raz na zawsze:

• dokumentacja dla deweloperów — hooki, moduły, motywy, core. Tu sprawdzasz sygnaturę hooka actionValidateOrder albo strukturę pliku głównego modułu.
• docs.prestashop-project.org — dokumentacja użytkownika panelu: podatki, strefy wysyłki, multistore, uprawnienia pracowników. Pisana językiem sklepowym, nie kodem.
• Referencja API / WebService — endpointy, dostępne zasoby, format odpowiedzi. Tu pytasz: „jakim zasobem pobrać zamówienia po dacie?”.
• Repozytorium GitHub PrestaShop/PrestaShop — issues, pull requesty, kod źródłowy. Odpowiada na pytanie „dlaczego to nie działa”, gdy zachowanie wygląda na błąd, a nie na Twoją literówkę.

Devdocs ma osobne wersjonowanie treści. Selektor w lewym menu zmienia artykuł, który czytasz, a numer wersji siedzi też w adresie URL. Link zapisany bez wersji potrafi dziś otworzyć inną gałąź niż w dniu, w którym go wkleiłeś do notatek.

Ostrzeżenie na koniec: wpisy z blogów i forów z lat 2015–2018 opisują 1.6. config/settings.inc.php, klasa Tools, plik defines.inc.php. W 1.7+ defines.inc.php już nie istnieje — konfiguracja leży w app/config/parameters.php. Wklejenie takiego kodu do sklepu 8.x kończy się białym ekranem albo cichym błędem w logach, którego szukanie zajmuje pół dnia.

Najpierw sprawdź wersję sklepu, potem otwieraj docs

Numer wersji to pierwsza informacja przed otwarciem jakiegokolwiek artykułu. Trzy sposoby, w kolejności od najszybszego:

1. Stopka back office — numer wersji widzisz na dole panelu. Pełne dane, łącznie z wersją PHP i konfiguracją serwera, są w Zaawansowane > Informacje.
2. Pliki na serwerze — w 1.6 w config/settings.inc.php znajdziesz linię _PS_VERSION_. W 1.7+ tego pliku nie ma; dane bazy i sekret znajdziesz w app/config/parameters.php (klucze database_version, database_prefix, secret).
3. Wersja PHP — ta sama sekcja Zaawansowane > Informacje. Rozjazd między wersją PHP a wersją sklepu to typowy powód błędów, których nie widać na pierwszy rzut oka.

Od 1.7.0 back office działa na Symfony. To zmienia sposób pracy: pojawia się profiler, cache w var/cache, komendy konsolowe. Jeśli trafisz na poradnik, który każe czyścić wyłącznie katalog cache/smarty — wiesz już, że pisano go dla 1.6.

Konsekwencja praktyczna: ten sam hook może mieć inne argumenty w 1.7 i w 8.x, a klasy zmieniają przestrzenie nazw. Sprawdzenie wersji zajmuje 30 sekund, debugowanie niezgodnego kodu w niedzielny wieczór — kilka godzin. Przy pracach większych niż poprawka szablonu, choćby przy integracjach z PrestaShop, wersję wpisuje się do specyfikacji przed pierwszym commitem, bo od niej zależy dobór modułów i sposób podpinania hooków.

Struktura devdocs PrestaShop: jak nawigować bez błądzenia

Devdocs ma powtarzalną strukturę, którą warto zapamiętać raz na zawsze:

• Modules — struktura modułu, rejestracja hooków, pliki konfiguracyjne, formularze w panelu.
• Themes — dziedziczenie szablonów, struktura katalogów, Smarty, przełączanie na nowszy stos frontowy.
• Core Development — komponenty sklepu: koszyk, zamówienie, katalog, reguły cenowe.
• Hooks — lista hooków z opisem i argumentami.
• API — Webservice oraz nowsze API.
• Testing i Contributing — testy automatyczne i zasady zgłaszania zmian.

Gdy wyszukiwarka devdocs nie znajduje nic sensownego, przełącz się na code search w GitHubie. Szukanie po nazwie klasy albo metody (np. CartRule::checkValidity) działa znacznie lepiej niż szukanie po opisie słownym. Filtr path:src/ zawęża wyniki do kodu core, a nie do testów i plików tłumaczeń.

Sekcje Core i zaawansowane API w devdocs bywają szkieletowe: opisują intencję, ale nie każdy parametr. Wtedy źródłem prawdy jest plik źródłowy. Praktyka z naszych wdrożeń: kopiuj sygnaturę metody z repozytorium, nie z artykułu. Między minorami zmieniają się typy argumentów i wartości domyślne, a artykuł zostaje w starej wersji.

Dobry nawyk: przy każdym wdrożeniu zapisuj link do artykułu w konkretnej wersji (z numerem w adresie), nie do strony głównej devdocs. Po pół roku nikt nie pamięta, czy dany hook był podpinany przed upgradem do 8.x, a wracanie do starej treści to najszybszy sposób, żeby nie powtarzać analizy. Ta sama zasada działa przy zadaniach łączących dokumentację z gotowymi modułami — choćby przy wdrożeniu PrestaShop GA4 eCommerce, gdzie kolejność zdarzeń w hookach trzeba sprawdzać w kodzie, nie w opisie na blogu.

Hooki w PrestaShop: gdzie jest pełna lista i jak ją czytać

W PrestaShop są dwa typy hooków i pomylenie ich to najczęstsza przyczyna sytuacji „moduł zainstalowany, a na stronie nic się nie zmieniło”. Hooki display... (np. displayHeader, displayHome, displayProductAdditionalInfo) odpowiadają za wyświetlanie w szablonie — moduł podpięty do nich zwraca HTML, który trafia w konkretne miejsce layoutu. Hooki action... (actionCartSave, actionOrderStatusUpdate, actionFrontControllerSetMedia) to zdarzenia w logice — nic nie renderują, tylko wykonują kod w danym momencie. Jeśli potrzebujesz i wyglądu, i logiki (np. banner plus zapis zdarzenia w bazie), rejestrujesz moduł na dwóch hookach — na jednym to nie zadziała.

• Rejestracja: w metodzie install() modułu wywołujesz $this->registerHook('displayHeader') albo tablicę nazw. W uninstall() dodaj $this->unregisterHook('displayHeader'), usuń własne tabele i wpisy w konfiguracji. Bez tego po odinstalowaniu zostają śmieci w tabeli ps_hook_module i w konfiguracji, które potrafią „wskrzesić” wywołania po ponownej instalacji modułu.
• Diagnostyka: pierwsze miejsce to Design > Positions (Pozycje) w back office — widać, który moduł siedzi na którym hooku i z jakiego pliku szablonu korzysta. Drugie to tryb debug (Zaawansowane > Wydajność), który zamiast białej strony pokazuje realny błąd; brakujący hook często kończy się właśnie pustym miejscem, a nie komunikatem.
• Czy hook istnieje w Twojej wersji: sprawdź w repozytorium kodu — src/Core/Hook/ w nowszych wersjach, klasy legacy w starszych, a pełną listę w pliku XML z definicjami hooków (install-dev/data/xml/hook.xml). Nazwa hooka zmieniona między 1.6 a 1.7+ nie zadziała w obie strony.
• Pułapka: hook istnieje, moduł jest na nim zarejestrowany, a i tak nic nie widać, bo motyw nie wywołuje go w szablonie. Rozwiązanie: nadpisz plik .tpl/Twig w motywie potomnym. Edycja plików core lub motywu bazowego zniknie przy najbliższej aktualizacji.

Jeśli hooki wykorzystujesz do pomiaru zdarzeń, kolejność prac i typowe błędy opisujemy w materiale o wdrożeniu DataLayer w PrestaShop.

API i WebService w dokumentacji: dwa różne światy

W PrestaShop równolegle działają dwa API i dokumentacja jednego nie opisuje drugiego. Klasyczny WebService jest dostępny od lat — włączasz go w Zaawansowane > WebService, tworzysz klucz i ustawiasz uprawnienia per zasób (GET/POST/PUT/DELETE osobno). Łączysz się Basic auth: login to klucz API, hasło puste. Zasoby siedzą pod /api/orders, /api/products, /api/customers; domyślny format to XML, JSON wymaga parametru ?output_format=JSON.

Praktyka, która oszczędza godziny: zamiast zgadywać pola, pobierz schemat zasobu — /api/products?schema=synopsis pokazuje strukturę, ?schema=blank pusty szkielet do wysłania. Paginację ustawiasz przez ?limit=0,100&sort=[id_ASC], filtrowanie po dacie przez ?date=1. Kody błędów czytaj dosłownie: 401 to zły lub wyłączony klucz, 403 brak uprawnień do metody, 404 zły zasób lub ID. Przy masowych operacjach (np. 5 tys. zamówień do ERP) licz się z limitami i czasem odpowiedzi — klasyczny WebService nie ma bulkowych endpointów, więc pracujesz paczkami i po kolei, najlepiej przez kolejkę.

Nowe API administracyjne oparte o API Platform (wprowadzane od 8.1, rozwijane w 9.x) to inny świat: inne uwierzytelnianie (OAuth2, client credentials), inne ścieżki i dokumentacja generowana jako OpenAPI. Status: dokładne ścieżki i sposób autoryzacji potwierdź w dokumentacji dla swojej wersji, bo kontrakt zmieniał się między wydaniami. Punkt wyjścia to PrestaShop Developer Documentation.

Uczciwe zastrzeżenie: przed integracją z ERP, płatnością czy kurierem zawsze potwierdź kontrakt na środowisku stagingowym — dokumentacja pokazuje kształt żądania, ale nie zachowanie konkretnej instalacji. Porządek w takich projektach opisujemy w artykule o integracjach z PrestaShop.

Motywy i szablony: dokumentacja motywów w praktyce

Motyw 1.7+ ma powtarzalną strukturę: katalog templates z plikami Twig, assets (css, js, obrazy), modules z nadpisanymi szablonami modułów oraz config/theme.yml. Ostatni plik jest kluczowy, bo właśnie tam deklarujesz motyw potomny (np. parent: classic). Motyw potomny dziedziczy wszystko po bazowym, a Ty nadpisujesz tylko te pliki, które naprawdę zmieniasz. Efekt: aktualizacja motywu bazowego nie kasuje Twojej pracy, bo nie tknąłeś jego plików.

Kolejność wyszukiwania szablonu jest sztywna i warto ją znać, żeby nie kopiować plików bez sensu. Dla modułu PrestaShop najpierw szuka szablonu w motywie (themes/<motyw>/modules/<moduł>/views/templates/...), a dopiero potem w katalogu modułu. Dla szablonów core (karta produktu, koszyk, checkout) Twoje pliki w themes/<motyw>/templates/ mają pierwszeństwo przed tymi z głównego katalogu templates/. Jeśli modyfikujesz kilka plików tego samego komponentu, sprawdź, czy nie nadpisujesz partiala, który jest używany w pięciu miejscach — zmiana odbije się wszędzie.

Przykłady w dokumentacji obejmują strukturę motywu i dziedziczenie Twig, natomiast pełny, działający wzorzec najszybciej obejrzysz w starter theme PrestaShop na GitHubie. Dokumentacja pokazuje koncept, kod pokazuje praktykę.

Pułapka, która zjada najwięcej czasu: po edycji szablonu nie widzisz zmian, bo działa cache. Wejdź w Zaawansowane > Wydajność, włącz opcję ponownego kompilowania szablonów przy zmianie plików i wyczyść cache. Gdy panel nie pomaga, usuń zawartość katalogu var/cache/ (w 1.6 dochodzi jeszcze katalog cache w motywie). Zanim zlecasz przebudowę wyglądu, warto policzyć zakres prac — pomaga w tym materiał o tym, kogo wybrać do wdrożenia PrestaShop i ile to kosztuje.

Czego w dokumentacji PrestaShop nie ma (i jak to obejść)

Dokumentacja PrestaShop istnieje w kilku warstwach i żadna z nich nie jest kompletna. Poniżej cztery luki, które trafiają się najczęściej, oraz metoda na każdą z nich.

1. Brak changelogów między minorami. Między 8.1.0 a 8.1.5 potrafi zmienić się zachowanie walidacji pola albo sygnatura metody, a opis w dokumentacji zostaje bez zmian. Źródłem prawdy są Pull Requesty i historia commitów w repozytorium. W praktyce: git log 8.1.0..8.1.5 -- classes/, a gdy szukasz konkretnej funkcji — git log -S "nazwaMetody". Numer commita wklej do zgłoszenia, żeby nie wracać do tego samego problemu za pół roku.

2. Przykłady kodu pod starą wersję. W dokumentacji dla deweloperów PrestaShop wciąż trafiają się fragmenty pisane pod 1.6 lub 1.7 bez adnotacji. Nie przepisuj ich bezmyślnie — sprawdź sygnaturę w kodzie: classes/, controllers/, src/. Jeśli artykuł mówi jedno, a metoda przyjmuje inne argumenty, wygrywa metoda.

3. Moduły z Marketplace bez dokumentacji technicznej. Część płatnych modułów nie ma żadnego opisu poza stroną sprzedażową. Czytaj kod: plik główny modules/nazwa/nazwa.php (rejestracja hooków, install/uninstall), katalog views/templates oraz override/. Override to najważniejsza informacja — mówi, co moduł nadpisuje w core i co przestanie działać po aktualizacji. Jeśli sklep ma kilka takich modułów, warto zaplanować to jak organizację wdrożenia integracji z PrestaShop, a nie gaszenie pożarów po kolei.

4. Testowanie poza produkcją. Postaw kopię sklepu na stagingu i korzystaj z sandboxa demo PrestaShop, żeby sprawdzić zachowanie bez ryzyka. Ta sama wersja PHP co na produkcji, inaczej wynik testu nic nie znaczy.

Zasada nadrzędna: gdy dokumentacja i kod się kłócą, kod wygrywa. Zapisz wersję PrestaShop, wersję PHP i numer commita, na których testowałeś.

Checklista przed wdrożeniem: dokumentacja jako narzędzie decyzji

Dokumentacja odpowiada na pytanie „jak to działa”. Brief wdrożeniowy odpowiada na „co robimy”. Bez drugiego pierwszy dokument bywa źródłem sporów. Pięć punktów do odhaczenia przed startem — opis wdrożenia krok po kroku znajdziesz też w materiale o organizacji wdrożenia sklepu PrestaShop.

• Wersja na piśmie. Przykładowy zapis: „PrestaShop 8.1.5, PHP 8.1, MySQL 8.0, motyw klasyczny”. Testuj na tej samej wersji PHP co produkcja. Poradnik dla 1.6 w sklepie 8.x to nie drobiazg, a cofanie zmian.
• Gotowy moduł czy własny. Kryterium jest jedno: czy wymaganie da się podpiąć pod istniejący hook. Lista hooków jest w dokumentacji i w kodzie core. Jest hook z potrzebnymi danymi — bierz gotowy moduł. Trzeba ruszyć core albo brakuje hooka w tym miejscu — pisz własny.
• WebService czy nowsze API. Zapisz, które funkcje (stany magazynowe, zamówienia, ceny) idą przez WebService z kluczem API i uprawnieniami per zasób, a które przez nowsze API. Zmiana po stronie API przy aktualizacji oznacza pracę po Twojej stronie — lepiej wiedzieć to przed podpisaniem zakresu.
• Kopia przed każdą zmianą. Baza: mysqldump --single-transaction. Pliki: tar z katalogu sklepu. Zanim „drobiazg z dokumentacji” wyląduje na produkcji, sprawdź, czy umiesz odtworzyć kopię. Backup bez testu odtworzenia to nie backup.
• Kto utrzymuje. Ustal, kto aktualizuje, kto robi backupy i kto reaguje na błąd w piątek o 20:00. Zapisz kanał zgłoszeń, czas reakcji i zakres prac.

Każdy z tych punktów jest odpowiedzią na zdanie „to nie było w dokumentacji”.

Kiedy dokumentacja nie wystarcza i warto to zlecić

Granica jest dość wyraźna. Dopóki pracujesz w panelu, na szablonie i na modułach, dokumentacja plus kod modułu zwykle wystarczają. Problemy zaczynają się wtedy, gdy w grę wchodzi kod core i wersjonowanie zmian.

Sygnały, że problem jest większy:

• Modyfikacje plików core zamiast modułu lub override — każda aktualizacja to ręczne przenoszenie zmian i sprawdzanie, czy nic się nie zgubiło.
• Brak wersjonowania zmian — pliki wgrywane FTP-em nie mają historii, więc nie ma czego cofnąć, gdy po zmianie sypie się koszyk.
• Rosnąca liczba override'ów i brak odpowiedzi na pytanie, który moduł nadpisuje który plik.
• Ten sam błąd wraca po każdej aktualizacji. To znak, że problem jest w strukturze, nie w pojedynczym pliku.

Własny moduł zamiast kolejnej wtyczki. To nie kwestia estetyki, a liczby zależności. Moduł pisany pod konkretny hook robi jedną rzecz, nie wpływa na pozostałe, nie konfliktuje z następnym rozszerzeniem i przechodzi aktualizację razem ze sklepem. Koszt: trzeba go utrzymywać.

Wycena. Uczciwa wycena to liczba godzin pomnożona przez stawkę, rozbita na etapy: analiza, implementacja, testy, wdrożenie, dokumentacja powdrożeniowa. Widełki zależą od zakresu — inny nakład to zmiana szablonu, a inny integracja magazynowa czy integracja PrestaShop z Allegro. Kwota bez opisu zakresu jest bezwartościowa, bo nie da się jej porównać z drugą ofertą.

Opieka po wdrożeniu. Utrzymanie sklepu to aktualizacje PrestaShop, PHP i modułów, backupy z testem odtworzenia, monitoring dostępności i błędów, poprawki w określonym czasie reakcji. Najlepiej z bezpośrednim kontaktem do dewelopera — bez pośredników, którzy przekazują zgłoszenia. Jak wygląda wybór wykonawcy od strony kosztów, opisaliśmy w tekście o wdrożeniu PrestaShop i kosztach.

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

Lista kontrolna do odklikania

• Wersja PrestaShop — Sprawdź w stopce back office lub w Zaawansowane > Informacje. Zrób to przed pierwszym klikiem w dokumentację.
• Wersja PHP — Ten sam ekran co wyżej albo phpinfo na serwerze. Od niej zależy, które wydania modułów i motywów w ogóle zadziałają.
• Status gałęzi — Ustal, czy pracujesz na 1.6 (po zakończeniu wsparcia), 1.7.8.x, 8.x czy 9.x — od tego zależy dostępność aktualnej dokumentacji i poprawek bezpieczeństwa.
• Wybór wersji w devdocs — W lewym menu ustaw wersję zgodną ze sklepem. Ta sama strona po przełączeniu opisuje inne metody i inne pliki.
• Właściwe źródło pytania — Ustawienie w panelu → dokumentacja użytkownika, hook/kod → devdocs, endpoint → referencja API, niespodziewany błąd → issues.
• Sygnatura metody — Porównaj z plikiem źródłowym w repozytorium dla swojej wersji, a nie z fragmentu artykułu.
• Rejestracja hooka — Sprawdź registerHook w install() oraz wyrejestrowanie w uninstall(). Upewnij się, że hook istnieje w Twojej wersji.
• Podłączenie w panelu — Design > Positions — czy moduł wisi na właściwym hooku i czy nie dubluje się z innym modułem.
• Tryb debug — Włącz na czas diagnozy, żeby zobaczyć błędy PHP i listę hooków na stronie. Wyłącz po testach — na produkcji nie zostawiaj go włączonego.
• Zgodność modułu i motywu — Sprawdź, czy moduł lub motyw deklaruje wsparcie dla Twojej gałęzi. Deklaracja w repo to nie to samo co test na Twojej instalacji.
• Zapisany link do dokumentacji — Przy każdym wdrożeniu zapisz adres artykułu z numerem wersji. Po pół roku wrócisz do tej samej treści, a nie do najnowszej.
• Zakres integracji — Zanim wejdziesz w dokumentację API, ustal listę systemów do połączenia i kolejność prac — zobacz, jak organizujemy to w integracjach z PrestaShop.
• Kto utrzymuje gałąź po EOL — Jeśli sklep działa na niewspieranej wersji, ustal z wykonawcą, kto i w jakim trybie reaguje na problemy, zanim pojawi się awaria.

Najczęściej zadawane pytania

Źródła i materiały

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