Tryb debug w PrestaShop — jak włączyć i używać [2026]

Tryb debug w PrestaShop (tryb deweloperski, _PS_MODE_DEV_) pokazuje pełne komunikaty błędów PHP zamiast białej strony lub ogólnego „Oops! An error occurred". To pierwsze narzędzie każdej diagnostyki: bez niego naprawa awarii to zgadywanie. Włączenie zajmuje minutę — jeden parametr w config/defines.inc.php. Poniżej: jak włączyć debug w PrestaShop 1.6, 1.7, 8 i 9, jak bezpiecznie go używać i jak czytać komunikaty. Diagnostyka awarii u specjalisty: 500–1 500 zł netto z raportem.

Najważniejsze: Tryb debug w PrestaShop włączasz w config/defines.inc.php: ustaw define('_PS_MODE_DEV_', true);. Na produkcji rób to tylko na kopii sklepu — komunikaty błędów widoczne dla klientów to wyciek informacji o serwerze. W PrestaShop 1.7+/8/9 działa też zmienna środowiskowa PS_MODE_DEV (.env). Po diagnozie wyłącz debug i wyczyść cache. Debug pokazuje pełny stack trace: plik, linię i klasę błędu — to 90% diagnozy awarii.

Po co włączać tryb debug

Domyślnie PrestaShop ukrywa błędy PHP przed użytkownikami: zamiast komunikatu pokazuje białą stronę albo ogólny ekran „Oops! An error occurred". Wygląda to „profesjonalnie", ale uniemożliwia diagnozę. Tryb debug odwraca to zachowanie:

• pokazuje pełny komunikat błędu z plikiem i linią kodu,
• wyświetla stack trace — ścieżkę wywołań prowadzącą do błędu,
• odsłania ostrzeżenia (Warning, Notice), które na produkcji są ukryte, a często zapowiadają poważniejszy problem,
• w PrestaShop 8/9 dodatkowo przełącza środowisko Symfony na dev (pełne logi w var/logs/dev.log).

Dzięki temu zamiast „sklep nie działa" wiesz dokładnie, że np. moduł X wywołuje nieistniejącą metodę na linii 214 swojego pliku.

Jak włączyć tryb debug — PrestaShop 1.7 / 8 / 9

1. Zaloguj się do plików sklepu (FTP/SFTP/SSH) — najlepiej na kopii środowiska.
2. Otwórz config/defines.inc.php.
3. Znajdź linię define('_PS_MODE_DEV_', false); i zmień na true.
4. Zapisz plik i odśwież stronę, na której występuje błąd.

W PrestaShop 8/9 możesz też użyć pliku .env w katalogu głównym: ustaw PS_MODE_DEV=true (i APP_ENV=dev, jeśli chcesz pełny tryb Symfony). To wygodniejsze, bo .env nie trafia do repozytorium tak łatwo jak defines.inc.php.

• Po zmianie wyczyść cache: panel → Parametry zaawansowane → Wydajność → Wyczyść cache, albo usuń zawartość var/cache z zachowaniem struktury katalogów.

Jak włączyć tryb debug — PrestaShop 1.6

W PrestaShop 1.6 parametr znajduje się w config/defines.inc.php i nazywa się tak samo: _PS_MODE_DEV_. Ustaw true, zapisz, odśwież stronę. Dodatkowo możesz włączyć _PS_DEBUG_SQL_ (podgląd zapytań SQL) — przydatne przy błędach bazy danych, ale włączaj je wyłącznie na kopii.

Czytanie komunikatów błędów

Komunikat w trybie debug ma stałą strukturę. Przykład

• **Fatal error:** Uncaught Error: Call to undefined method PaymentModule::validateOrder2() in /var/www/shop/modules/mojmodul/mojmodul.php on line 214

Co z tego odczytasz

• typ błędu — Fatal error zatrzymuje stronę, Warning to ostrzeżenie,
• klasa i metoda — PaymentModule::validateOrder2() — czego brakuje,
• plik i linia — /modules/mojmodul/mojmodul.php:214 — winny moduł,
• stack trace — kolejne wywołania pokazują, jak sklep doszedł do błędu.

Najczęstsze komunikaty i co oznaczają

• **| failed to open stream:** Permission denied | Uprawnienia plików | Katalogi 755, pliki 644 | | SQLSTATE[...] | Błąd bazy danych | Sprawdź tabelę i zapytanie z komunikatu | | Cannot redeclare | Konflikt override'ów | Szukaj duplikatu w override/ |

• ## Bezpieczeństwo: debug tylko na kopii

Tryb debug na produkcji oznacza, że każdy odwiedzający może zobaczyć ścieżki serwera, fragmenty konfiguracji i zapytania SQL. To zaproszenie dla atakujących. Zasady:

• włączaj debug na kopii sklepu (staging) — pełna kopia plików i bazy,
• jeśli musisz zdiagnozować coś na produkcji, włącz debug na kilka minut, w niskim ruchu, i natychmiast wyłącz,
• po wyłączeniu debug wyczyść cache — komunikaty nie mogą zostać zapisane w cache'owanych stronach,
• nigdy nie zostawiaj _PS_MODE_DEV_ na true po zakończeniu prac.

Uwaga: Debug na produkcji odsłania przed klientami ścieżki plików, nazwy tabel bazy i konfigurację serwera. Jeśli nie masz kopii środowiska, zrób ją najpierw — diagnostyka na kopii to standard, nie luksus.

Gdy nie masz dostępu do plików

Bez dostępu do FTP/SSH też zdiagnozujesz awarię

• poproś hosting o włączenie display_errors w PHP na kopii domeny,
• odczytaj logi PHP z panelu hostingu (error_log, logi dzienne),
• sprawdź var/logs/ przez menedżer plików w panelu,
• poproś support hostingu o ostatnie wpisy błędów PHP z Twojego konta — hostingi udostępniają je standardowo.

Logi zawierają te same informacje co ekran debug, tylko w formie plików — instrukcję ich czytania znajdziesz w logi PrestaShop.

Tryb debug a inne narzędzia diagnostyczne

Tryb debug to fundament, ale nie jedyne narzędzie

• logi — działają zawsze, także na produkcji; uzupełniają debug o historię,
• _PS_DEBUG_PROFILING_ — profilowanie zapytań SQL i czasu wykonania (PrestaShop 1.7+), przydatne przy wydajności,
• _PS_DEBUG_SQL_ — podgląd zapytań SQL, pomocny przy błędach bazy,
• konsola deweloperska przeglądarki — błędy JavaScript i żądań sieciowych (np. gdy mapa Paczkomatów się nie ładuje).

Profilowanie włączaj tylko na kopii — potrafi mocno obciążać sklep.

Najczęściej zadawane pytania

Jak włączyć tryb debug w PrestaShop 8?

W config/defines.inc.php ustaw define('_PS_MODE_DEV_', true); albo w pliku .env ustaw PS_MODE_DEV=true. Po zmianie wyczyść cache (panel → Wydajność lub usunięcie zawartości var/cache). Rób to na kopii sklepu — na produkcji tylko na krótko i w niskim ruchu.

Czy tryb debug spowalnia sklep?

Tak — debug wyłącza część cache'owania i dodaje narzut na każde żądanie, dlatego nie zostawia się go włączonego na produkcji. Do diagnostyki to nie przeszkadza: ładujesz jedną stronę i czytasz błąd. Po diagnozie wyłącz debug i wyczyść cache.

Biała strona nawet w trybie debug — dlaczego?

Biała strona przy włączonym _PS_MODE_DEV_ oznacza błąd na poziomie serwera (PHP-FPM nie startuje, brak pamięci procesu, błąd .htaccess) albo że debug nie został faktycznie włączony (cache konfiguracji). Sprawdź logi serwera — tam będzie przyczyna. Procedura: biała strona PrestaShop.

Czy tryb debug pokaże błędy modułu płatności?

Tak, każdy błąd PHP w module płatności zostanie wyświetlony z plikiem i linią. Pamiętaj jednak, że część problemów płatności to błędy logiczne (webhooki, statusy zamówień), których debug nie pokaże — ich diagnoza wymaga logów modułu. Więcej: checkout nie działa.

Źródła i narzędzia

• PrestaShop DevDocs — konfiguracja środowiska deweloperskiego
• PrestaShop — dokumentacja
• PHP — obsługa błędów

👉 Nie możesz zdiagnozować awarii sam? Włącz debug na kopii i prześlij komunikat — formularz kontaktowy lub kontakt@informatix.com.pl. Zobacz też pomoc techniczna PrestaShop.

📖 Zobacz też: biała strona w PrestaShop, błąd 500 i logi PrestaShop.