Jak włączyć debug mode PrestaShop

Tryb debugowania w PrestaShop to prosty, ale niezwykle skuteczny sposób na szybkie namierzenie przyczyn problemów: od białych ekranów, przez nieoczekiwane błędy, po konflikty modułów i motywów. W tej instrukcji krok po kroku pokażę, jak bezpiecznie włączyć debug z panelu oraz w plikach, jak czytać komunikaty i logi, jak czyścić cache i wymuszać kompilacja szablonów, a także jak wrócić do ustawień produkcyjny i co sprawdzić przed publikacją. To przewodnik praktyczny – dla osób technicznych i nietechnicznych.

Co to jest tryb debug i kiedy warto go włączać

Na czym polega tryb debug

Tryb debug w PrestaShop włącza dodatkowe mechanizmy diagnostyczne, które zamiast ukrywać problemy, pokazują je wprost na ekranie i/lub zapisują szczegółowo w dziennikach. Otrzymujesz ślady wywołań, ostrzeżenia PHP, informacje o nieprawidłowej konfiguracji, a niekiedy także belkę narzędziową środowiska Symfony (w nowszych wydaniach). To znacznie skraca czas potrzebny na wykrycie sedna problemu: wadliwego modułu, zbyt restrykcyjnych uprawnień plików, błędów w motywie, błędnej wersji PHP lub mylących wpisów w .htaccess.

Różnica między trybem deweloperskim a produkcyjnym

PrestaShop rozróżnia dwa główne stany pracy: deweloperski (development) i produkcyjny (production). W stanie produkcyjnym błędy są zazwyczaj ukrywane, a aplikacja agresywnie buforuje wyniki, aby działać szybko i stabilnie dla klientów. W stanie deweloperskim pojawią się jawne komunikaty, a system ogranicza lub wyłącza część mechanizmów buforowania, aby zmiany w kodzie były widoczne od razu. W praktyce oznacza to szybszą diagnostykę, ale także potencjalne ujawnianie szczegółów środowiska – dlatego nigdy nie pozostawiaj sklepu na długo w trybie debug na publicznej instancji.

Kiedy warto włączać debug

• Gdy widzisz biały ekran (blank page) lub kod 500 i nie ma treści błędu.
• Po aktualizacji modułu, motywu lub samej platformy, aby zweryfikować potencjalne konflikty.
• Gdy panel lub front działa niestabilnie, ładuje się bardzo wolno albo pojawiają się sporadyczne błędy zapisu.
• Podczas prac nad nowym motywem lub modułem, by szybciej iterować.
• Gdy musisz prześledzić proces zakupowy, integracje płatności, webhooki lub zadania CRON.

Ryzyka i zasady bezpieczeństwa

Tryb debug może ujawnić stack trace, ścieżki na serwerze, wersje bibliotek, a nawet fragmenty konfiguracji. Aby zminimalizować ryzyko:

• Odpalaj debug tylko wtedy, gdy jest konieczny i tylko na czas diagnostyki.
• Jeśli to możliwe, pracuj na środowisku testowym (staging) z danymi zamaskowanymi.
• Ogranicz dostęp do sklepu, np. przez IP whitelisting, proste hasło HTTP Auth lub tryb konserwacji.
• Po zakończeniu analiz natychmiast wróć do ustawień produkcyjnych i wyczyść bufor.

Włączenie debug mode w panelu administracyjnym

Gdzie znaleźć opcję w różnych wersjach

W wersjach 1.6 oraz 1.7/8.x lokalizacja ustawień wydajności jest podobna, choć nazewnictwo bywa nieco inne. Zaloguj się do panelu administracyjnego i przejdź do: Parametry zaawansowane → Wydajność (Advanced Parameters → Performance). Szukaj sekcji Debugowanie lub Debug mode. W nowszych wydaniach zobaczysz przełącznik Debug mode oraz dodatkowe opcje związane z kompilacją szablonów i buforowaniem Smarty.

Krok po kroku: włączenie z panelu

• Zaloguj się do panelu administratora na koncie z odpowiednimi uprawnieniami.
• Wejdź w Parametry zaawansowane → Wydajność.
• Znajdź przełącznik Debug mode i ustaw na Włączony.
• Jeśli diagnozujesz motyw, rozważ ustawienie Template compilation (Kompilacja szablonów) na Force compile oraz wyłączenie cache Smarty (Disable cache) – tylko na czas testów.
• Zapisz zmiany. Odśwież stronę problematycznego widoku we froncie lub w panelu.

Po włączeniu debug zobaczysz komunikaty błędów bezpośrednio na stronie lub pojawi się belka narzędziowa dewelopera. Jeśli strona nadal jest pusta, sprawdź logi serwera i foldery z dziennikami PrestaShop.

Weryfikacja działania

Aby potwierdzić, że tryb debug rzeczywiście działa, umyślnie odwiedź adres, który generuje ostrzeżenie (np. niekompatybilną podstronę modułu), lub sprawdź, czy na dole strony pojawia się pasek diagnostyczny. Dodatkowo wejdź do Katalog → Produkty i dokonaj drobnej zmiany – jeżeli kompilacja szablonów i wyłączony cache działają, odświeżona treść będzie widoczna natychmiast po zapisie.

Gdy panel jest niedostępny (błąd 500)

Jeśli nie możesz zalogować się do panelu, włącz debug na poziomie plików (opis niżej). To zadziała nawet w sytuacji, gdy panel administracyjny przestał funkcjonować po aktualizacji lub instalacji modułu.

Włączenie debug mode w plikach konfiguracyjnych

defines.inc.php – uniwersalna metoda

Najbardziej klasyczny sposób działa w PrestaShop 1.5–1.7 i często w 8.x:

• Wejdź na serwer (SFTP/SSH/Panels) i wykonaj kopię zapasową pliku: config/defines.inc.php.
• Otwórz plik i znajdź linię z constantą _PS_MODE_DEV_. Jeśli jej nie ma, dodaj ją wśród innych define.
• Ustaw: define(’_PS_MODE_DEV_’, true);
• Zapisz plik i wyczyść katalogi bufora (patrz sekcja o cache).

To wymusza tryb deweloperski niezależnie od ustawień panelu. Jeśli po tej zmianie wciąż masz biały ekran, włącz też raportowanie błędów PHP na poziomie serwera lub dopisz tymczasowo: ini_set(’display_errors’, '1′); error_reporting(E_ALL); w górnej części pliku wejściowego – tylko na czas testów.

APP_ENV=dev – integracja Symfony w 1.7/8.x

W odsłonach 1.7/8.x PrestaShop korzysta z elementów Symfony. Dodatkowo możesz przestawić środowisko aplikacji:

• W pliku .env (lub w zmiennych środowiskowych) ustaw: APP_ENV=dev.
• W niektórych konfiguracjach przydatne bywa także APP_DEBUG=1.
• Po zmianach usuń katalog var/cache/prod, aby aplikacja wstała w trybie dev z nową konfiguracją.

Pamiętaj, że to ustawienie jest potężne – belka debugowa i szczegółowe opisy wyjątków nie powinny być publicznie dostępne w sklepie produkcyjnym.

Wyłączenie override i dodatkowe przełączniki

Problemy często powodują pliki override oraz niestandardowe moduły. W pliku config/defines.inc.php możesz dodać lub zmodyfikować:

• define(’_PS_DEBUG_PROFILING_’, true); – włącza wbudowany profiler (czasy zapytań SQL, hooki, użycie pamięci).
• W panelu (jeśli dostępny): Wyłącz wszystkie nadpisania (Disable all overrides) i Wyłącz moduły niestandardowe – szybki test izolujący problem.

Profiler jest szczególnie przydatny, gdy problemem nie jest błąd krytyczny, tylko spadek wydajności lub N+1 queries.

Bezpieczeństwo edycji plików

Przed edycją zrób kopię zapasową. Na hostingu z OPcache po zapisaniu pliku możesz nie od razu zobaczyć efekt – zrestartuj PHP-FPM lub chwilowo obniż TTL OPcache. Pilnuj także właściwych uprawnień i właściciela plików (np. www-data:www-data, 0644/0755). Niewłaściwe prawa dostępu mogą same w sobie wywoływać błędy 500 i komunikaty o braku możliwości zapisu do katalogów cache i logów.

Dodatkowe ustawienia: błędy, logi, cache i kompilacja

Wyświetlanie błędów PHP i konfiguracja serwera

Nawet przy włączonym debug PrestaShop może zostać stłumiony output błędów przez konfigurację PHP. Sprawdź:

• display_errors – w środowisku testowym ustawione na On.
• error_reporting – najlepiej E_ALL w trakcie diagnozy.
• log_errors – Włączone, z poprawną ścieżką do pliku dziennika.

Na środowisku publicznym pozostaw wyświetlanie błędów wyłączone, a jedynie loguj je na serwerze. To ogranicza ekspozycję wrażliwych informacji.

Gdzie znaleźć logi PrestaShop i serwera

Dzienniki aplikacji bywają w kilku miejscach:

• var/logs/ (w starszych 1.7) lub var/log/ (w 8.x) – logi aplikacji/Symfony.
• logs/ w katalogu głównym (niektóre dystrybucje i moduły).
• log PHP/serwera: error.log w katalogu Apache/nginx lub w panelu hostingu.

W logach szukaj pierwszej przyczyny (causative exception), nie tylko ostatniego komunikatu. Zwracaj uwagę na stack trace i ścieżki, które wskazują moduł, plik motywu albo hook, w którym nastąpiła awaria.

Ręczne czyszczenie cache

Po zmianach konfiguracyjnych i w trakcie testów czyść bufor:

• PrestaShop 1.7/8.x: usuń katalog var/cache/prod i/lub var/cache/dev (aplikacja odbuduje je sama).
• PrestaShop 1.6: wyczyść cache/smarty/compile oraz cache/smarty/cache, a także cache/class_index.php.
• Jeśli używasz Varnish/Redis/OPcache – pamiętaj o ich odświeżeniu.

To ważne, bo wiele błędów „znika” dopiero po zrzuceniu warstw buforowania – w przeciwnym razie widzisz efekt sprzed zmian.

Kompilacja Smarty i widoczność zmian

Pracując nad motywem, w panelu ustaw:

• Kompilacja szablonów (Template compilation): Force compile.
• Cache Smarty: Wyłączone.

Gdy zakończysz prace, przywróć ustawienia produkcyjne: Kompiluj szablony, jeśli pliki zostały zmienione (lub Nigdy nie kompiluj na bardzo wydajnych serwerach) i włącz buforowanie. Różnica w wydajności jest znaczna, dlatego ustawienia deweloperskie utrzymuj wyłącznie podczas testów.

Toolbar i profilowanie

W 1.7/8.x, przy APP_ENV=dev i _PS_DEBUG_PROFILING_=true, zobaczysz profilery:

• Belka Symfony – informacje o czasie, zapytaniach SQL, wyjątkach, wysyłanych nagłówkach.
• Profiler PrestaShop – rozbicie czasu na hooki, zapytania, szablony; świetne do szukania wąskich gardeł.

Uważnie przeanalizuj najwolniejsze zapytania i fragmenty motywu. To często wystarczy, by skrócić TTFB i przywrócić płynność koszyka oraz płatności.

Diagnostyka najczęstszych problemów z wykorzystaniem debug

Błędy po aktualizacji modułów lub samej platformy

Jeśli po aktualizacji pojawił się błąd 500:

• Włącz debug w pliku defines.inc.php lub z panelu (jeśli dostępny).
• Wyłącz wszystkie override i moduły niestandardowe – jeśli błąd znika, włączaj je po kolei, aż trafisz winnego.
• Sprawdź kompatybilność modułu z Twoją wersją PrestaShop i PHP. Niekompatybilne wersje to częsty powód krytycznych wyjątków.

Często wystarczy wycofać ostatnią aktualizację lub pobrać poprawioną wersję modułu.

Konflikty motywu i błędy Smarty

Typowe symptomy to komunikaty o brakującym bloku, nieistniejącym indeksie tablicy lub problemach z kompilacją. Działaj tak:

• Wymuś kompilację i wyłącz cache Smarty.
• Sprawdź, czy nadpisania w motywie (np. nadpisane hooki lub szablony) pasują do Twojej wersji modułów i rdzenia.
• Zajrzyj w logi – plik i linia błędu zwykle wskazują konkretny template .tpl.

Gdy problem dotyczy jednego modułu, podmień tylko jego pliki motywu, zamiast zmieniać cały theme.

Wydajność: spowolnienia, przeciążenia i N+1 queries

Jeżeli strona działa, ale wolno:

• Włącz profiler i porównaj, które hooki zabierają najwięcej czasu.
• W logach SQL sprawdź liczbę zapytań na stronę – seryjne odwołania (N+1) są widoczne jak na dłoni.
• Zaktualizuj indeksy bazy danych (np. reindeksacja produktów) i zbadaj brakujące indeksy w problematycznych tabelach.
• Oceń kosztowność modułów – nieużywane wyłącz lub usuń.

Zanim będziesz optymalizować serwer, sprawdź warstwę aplikacji. To tam zwykle zyskuje się najwięcej.

Uprawnienia, właściciel i open_basedir

W trybie debug często ujawniają się problemy z zapisem do katalogów var/cache, img, download, translations. Upewnij się, że:

• Właścicielem plików jest użytkownik PHP (np. www-data), a nie użytkownik SFTP.
• Uprawnienia nie są zbyt restrykcyjne (zwykle 775 dla katalogów, 664 dla plików – zależnie od serwera).
• open_basedir nie blokuje zapisu do katalogów tymczasowych.

Błędne uprawnienia potrafią „ukryć” przyczynę problemu – debug wyświetli wówczas jasny komunikat o braku możliwości zapisu.

Integracje: płatności, przewoźnicy, API

Przy problemach z bramkami płatności lub API włącz debug i prześledź:

• Żądania i odpowiedzi – najlepiej w logach modułu oraz serwera (czasem pomocne są narzędzia proxy jak mitm lub logi webhooków).
• Walidację danych – czy waluty, adresy, wagi i stawki VAT są zgodne z wymaganiami integracji.
• Obsługę wyjątków w module – komunikaty debug zwykle wskażą brakujące biblioteki lub błędy konfiguracji.

Po zakończeniu testów pamiętaj o powrocie do trybu produkcyjnego i o ukryciu kluczy API.

Jak wyłączyć debug i posprzątać po diagnostyce

Przywrócenie trybu produkcyjnego

Gdy naprawisz usterkę:

• W panelu: Parametry zaawansowane → Wydajność → Debug mode: Wyłącz.
• W pliku config/defines.inc.php: ustaw define(’_PS_MODE_DEV_’, false); lub usuń/zakomentuj wpis.
• Jeśli zmieniałeś .env: ustaw APP_ENV=prod i APP_DEBUG=0.

Nigdy nie pozostawiaj debug na sklepie publicznym – to zwiększa powierzchnię ataku i może ujawnić dane środowiska.

Wyczyszczenie cache i ponowna kompilacja

Po wyłączeniu debug posprzątaj:

• Usuń var/cache/dev i var/cache/prod (1.7/8.x) lub katalogi Smarty (1.6), aby odbudować czysty bufor.
• Przywróć ustawienia Smarty: kompiluj tylko przy zmianie plików i włącz cache.
• Włącz ponownie rozsądne poziomy kompresji, minifikacji i konsolidacji zasobów, jeśli wcześniej je wyłączyłeś.

Sprawdź kluczowe ścieżki zakupowe (lista produktów, koszyk, checkout, płatność) już w trybie produkcyjnym – upewnij się, że wszystko działa bez błędów i z oczekiwaną szybkością.

Dodatkowe kontrole i regeneracja .htaccess

Po większych zmianach warto:

• W panelu: Preferencje → SEO i URL → Zapisz (regeneruje .htaccess przy włączonych przyjaznych URL-ach).
• Zweryfikować zgodność wersji PHP i rozszerzeń (intl, gd, curl, mbstring, zip) z Twoją wersją PrestaShop.
• Upewnić się, że integracje (płatności, wysyłka, ERP) działają w trybie produkcyjnym i nie logują zbędnych danych.

Regeneracja .htaccess często rozwiązuje błędy 404 po migracji lub zmianie hostingu.

Lista kontrolna po debugowaniu

• Debug wyłączony w panelu i/lub w plikach.
• APP_ENV=prod i APP_DEBUG=0 (jeśli używasz .env).
• Bufory wyczyszczone; OPcache/Redis/Varnish odświeżone.
• Ustawienia Smarty przywrócone do produkcyjnych.
• Override i moduły niezbędne włączone, zbędne wyłączone.
• Logi czyste; brak nowych wpisów o błędach krytycznych.
• Monitoring dostępności oraz alerty skonfigurowane (np. e-mail/Slack po błędach 500).

Podsumowując w praktyce: włączasz debug, identyfikujesz przyczynę, testujesz poprawkę na środowisku testowym, wdrażasz, wracasz do ustawień produkcyjnych i czyścisz bufor. Dzięki temu tryb debug staje się bezpiecznym i skutecznym narzędziem, a nie stałym elementem konfiguracji. W razie trudnych przypadków sięgnij po profiler, przyjrzyj się zapytaniom SQL, sprawdź moduły override i pamiętaj o podstawach: aktualnych backupach oraz kontroli wersji zmian w katalogu config.