Problemy PrestaShop: biały ekran i błędy 500

Sklep przestał działać. Co zrobić w ciągu najbliższych dziesięciu minut.

Po dziesięciu latach i 159 modułach pracujących produkcyjnie poznaliśmy większość scenariuszy, w których sklep PrestaShop potrafi się wywrócić, białe ekrany, błędy 500, pętle logowania do panelu, przyciski „zapisz”, które po cichu nic nie robią, finalizacje zamówienia zawieszające się na kroku 3. Ta strona to procedura, której używamy we własnej skrzynce wsparcia, zanim sięgniemy do choćby jednej linii kodu.

Największym błędem, jaki obserwujemy, jest odruch paniki: ktoś zauważa, że sklep nie działa, zaczyna zmieniać pięć rzeczy naraz i już nikt nie wie, co naprawiło problem, a co pogłębiło awarię. Tak nie należy postępować. Metoda, która działa, jest nudna: odczytać błąd, odczytać logi, zmienić jedną rzecz, zweryfikować, powtórzyć.

Zanim zmieni się cokolwiek na działającym sklepie, warto wykonać zrzut bazy danych i archiwum plików. Jeśli poprawka pogorszy sytuację, potrzebna jest droga powrotna, a założenie „przecież zapamiętam, co zmieniłem” nigdy nie przetrwa prawdziwej awarii.

1. Włączanie trybu debugowania bez strzelania sobie w stopę

Strona Logi w panelu administracyjnym PrestaShop 8.

Każdy błąd przechwycony przez PrestaShop trafia tutaj wraz z poziomem ważności, znacznikiem czasu i kontekstem obiektu. Warto zajrzeć tu, zanim sprawdzi się logi serwera.

Domyślnie PrestaShop ukrywa błędy, dobre dla klientów, bezużyteczne dla nas. Tryb debugowania to pierwszy przełącznik, który włączamy przy każdym zgłoszeniu diagnostycznym.

PrestaShop 1.6 i 1.7

Należy zedytować plik config/defines.inc.php:

define('_PS_MODE_DEV_', true);  // Zmiana false na true

To włącza wyświetlanie błędów, wyłącza cache Smarty i podnosi error_reporting do E_ALL. Od wersji 1.7.7 dostępny jest również pasek debugowania Symfony na dole każdej strony, sam ten pasek oszczędził nam wiele godzin.

PrestaShop 8.x i 9.x

Ten sam trik z plikiem defines.inc.php nadal działa, ale PS 8+ odczytuje również plik .env:

# .env lub .env.local
APP_ENV=dev
APP_DEBUG=1

Gdy PrestaShop w ogóle się nie uruchamia

Jeśli błąd wystąpi, zanim PrestaShop wczyta własną konfigurację, po przełączeniu trybu debugowania otrzymamy pustą stronę bez żadnej zmiany. Należy zmusić PHP do bezpośredniej komunikacji, dodając na górze pliku index.php:

ini_set('display_errors', 1);
error_reporting(E_ALL);

To omija całkowicie PrestaShop i kieruje surowy błąd krytyczny PHP do przeglądarki. Należy to usunąć w tej samej chwili, w której znamy odpowiedź.

Nigdy nie należy pozostawiać trybu debugowania włączonego na produkcji. Ujawnia on ścieżki plików, dane logowania do bazy danych, tajne tokeny oraz całe środowisko techniczne każdemu, kto wywoła błąd. Audytowaliśmy sklepy, w których był on włączony przez miesiące. Każdy z nich był incydentem bezpieczeństwa czekającym na opisanie.

2. Biały ekran śmierci

Całkowicie pusta strona oznacza, że PHP napotkał błąd krytyczny, lecz display_errors jest wyłączone. Błąd istnieje. Został gdzieś zapisany. Wystarczy znaleźć, gdzie.

Krok 1: odczytać log

Błąd krytyczny znajduje się w jednym z poniższych miejsc:

• var/logs/prod.log (PS 1.7)
• var/log/prod.log (PS 8+ i 9)
• Log błędów Apache lub Nginx (błędy krytyczne na poziomie serwera)
• Log błędów PHP (ścieżka znajduje się w php.ini; na hostingu współdzielonym jest to zwykle ~/logs/error.log)

Bez wcześniejszego odczytania logu działa się po omacku. Log zawiera plik, numer linii i komunikat. To jest odpowiedź.

Krok 2: włączyć tryb debugowania

Jeśli nie ma dostępu do logów (hosting współdzielony bez SSH, panika w danej chwili), należy przełączyć _PS_MODE_DEV_ i odświeżyć stronę. Teraz błąd wyświetli się w przeglądarce.

Krok 3: kontrola sprawności z poziomu CLI

Jeśli nawet strona debugowania jest pusta, uszkodzony jest sam proces uruchamiania. Warto przetestować z poziomu wiersza poleceń:

php -l config/defines.inc.php           # sprawdzenie składni
php -r "require 'config/config.inc.php';"  # test pełnego wczytania

Pięć przyczyn, które obserwujemy we wsparciu

• Wyczerpana pamięć. Należy ustawić memory_limit = 512M w php.ini. 256M to dolna granica dla PS 1.7+, 512M dla PS 8+, przy niższej wartości jeden masowy import ją rozsadzi.
• Niezgodność wersji PHP. PS 1.6 nie działa na PHP 7.4+. PS 1.7.0–1.7.6 nie działa na PHP 8.0+. PS 9.x wymaga PHP 8.1+. Widzieliśmy, jak rutynowa aktualizacja PHP na serwerze położyła pięć sklepów naraz, ponieważ nikt nie sprawdził tabeli zgodności.
• Błąd krytyczny modułu. Ostatnio zainstalowany moduł to podejrzany numer jeden. Należy zmienić nazwę jego katalogu przez FTP: modules/problem_module → modules/problem_module_disabled. PrestaShop go pominie, a sklep się wczyta.
• Uszkodzony cache. Należy wyczyścić var/cache/ (PS 1.7+) lub cache/smarty/compile/ (PS 1.6). Gdy wdrożenie zapisze plik cache tylko częściowo, kolejne żądanie odczytuje śmieci i kończy się błędem.
• Uszkodzony override. Należy zmienić nazwę całego katalogu override/. Jeśli sklep wróci do życia, problem został zlokalizowany. Następnie należy zawęzić go, ponownie wprowadzając pliki jeden po drugim.

3. Błąd 500 Internal Server Error

Błąd 500 to sygnał od serwera, że coś poszło nie tak, zanim PHP zdążyło się odezwać. Błąd często nie znajdzie się nawet w logach PrestaShop, najpierw należy sprawdzić log błędów Apache lub Nginx.

Pułapka pliku .htaccess

Najczęstsza przyczyna, jaką obserwujemy. Można to sprawdzić natychmiast:

mv .htaccess .htaccess.bak

Jeśli sklep się wczyta (z uszkodzonymi adresami URL i brzydkimi parametrami zapytań), problemem był plik .htaccess.

• mod_rewrite niewłączony. a2enmod rewrite && systemctl restart apache2. Wymagany do przyjaznych adresów URL.
• AllowOverride None. Wirtualny host musi zezwalać na reguły PrestaShop. Należy zmienić na AllowOverride All.
• Dyrektywy blokowane przez hosting. Niektóre hostingi współdzielone zakazują Options lub php_value. Należy zakomentować bloki, dopóki błąd 500 nie zniknie.
• Regeneracja. Ustawienia sklepu → Ruch i SEO → „Wygeneruj plik .htaccess” odbudowuje go na podstawie własnego szablonu PrestaShop.

Uprawnienia plików

Katalogi 755, pliki 644, katalogi zapisywalne (var/cache, img, upload) 775. Każdy, kto zaleca chmod 777, nie ma racji i niemal na pewno gdzie indziej również otwiera lukę bezpieczeństwa.

find /path/to/prestashop -type d -exec chmod 755 {} \;
find /path/to/prestashop -type f -exec chmod 644 {} \;

Limity PHP, które warto ustawić raz i zapomnieć

memory_limit = 512M
max_execution_time = 300
max_input_vars = 10000
post_max_size = 64M
upload_max_filesize = 64M

max_input_vars to cichy zabójca, strony produktów PrestaShop z kombinacjami łatwo przekraczają domyślną wartość 1000, a PHP po prostu odrzuca resztę żądania POST bez żadnego błędu. Zapisuje się produkt, połowa pól wraca do poprzednich wartości i nic nie trafia do logów.

4. Konflikty modułów

Moduły powodują więcej awarii sklepów niż jakakolwiek inna pojedyncza kategoria, i to z dużą przewagą. Schemat jest niemal zawsze taki sam: instalacja nowego modułu i coś innego przestaje działać. Dwa moduły próbują podpiąć się w tym samym miejscu lub nadpisać tę samą klasę, a drugi zainstalowany przegrywa.

Metoda izolacji

1. Wyłączyć każdy moduł firm trzecich w Menedżerze modułów.
2. Potwierdzić, że problem zniknął.
3. Włączać ponownie partiami, a następnie pojedynczo, testując po każdym.

Jeśli sam panel jest uszkodzony, należy wyłączyć moduł z poziomu bazy danych:

UPDATE ps_module SET active = 0 WHERE name = 'module_name';
-- Lub zmienić nazwę katalogu przez SSH/FTP:
mv modules/problem_module modules/problem_module.bak

Konflikty override

Dwa moduły nie mogą nadpisać tej samej metody klasy. Druga instalacja kończy się jednoznacznym niepowodzeniem z komunikatem „method X is already overridden by module Y”. Kolizji należy szukać w override/classes/ i override/controllers/. Jeśli ręcznie usuwa się plik override, należy skasować var/cache/*/class_index.php, w przeciwnym razie PrestaShop nadal używa zapisanej w cache wersji mapy override i będzie się wydawać, że nic się nie zmieniło.

Kolejność hooków

Gdy dwa moduły rejestrują się na tym samym hooku, pozycja decyduje o tym, który renderuje się jako pierwszy. Należy zmienić kolejność w Wygląd → Pozycje lub odpytać bezpośrednio ps_hook_module, aby zobaczyć bieżącą kolejność.

Otwierając zgłoszenie u dewelopera modułu, warto dołączyć: dokładny wpis z logu, wersję PrestaShop, wersję PHP, pozostałe aktywne moduły oraz kroki do odtworzenia. „Sklep się popsuł” to zgłoszenie na 48 godzin; „hookActionCartSave z modułu X zgłasza błąd z tym śladem stosu na PS 8.1.4 + PHP 8.2” to zgłoszenie na 2 godziny.

Jeśli problem dotyczy modułu komercyjnego i nie da się go rozwiązać samodzielnie, warto otworzyć zgłoszenie do wsparcia z przygotowanymi takimi informacjami. Precyzyjna awaria hooka, override lub żądania jest szybsza do zdiagnozowania niż mgliste „strona nie działa”.

5. Problemy z cache

„Wyczyściłem cache i nie pomogło” niemal zawsze oznacza, że wyczyszczony został niewłaściwy cache. PrestaShop uruchamia co najmniej pięć warstw pamięci podręcznej równolegle i żadna z nich nie wie o pozostałych.

Pięć warstw

• Smarty. Skompilowane pliki .tpl w var/cache/prod/smarty/. To właśnie czyści się po kliknięciu „Wyczyść cache” w panelu.
• Symfony. Skompilowany kontener usług, trasy, tłumaczenia w var/cache/prod/. PS 8+ mocno na nim polega, zmiany konfiguracji, które „nie zadziałały”, zwykle oznaczają nieaktualny cache Symfony.
• OPcache. Kod bajtowy PHP w pamięci współdzielonej. Niewidoczny w systemie plików, nienaruszany przez usuwanie plików i źródło połowy zgłoszeń „wgrałem poprawkę, ale błąd nadal jest”.
• Cache obiektów. Cache zapytań do bazy danych PrestaShop (oparty na plikach lub na Redis).
• Przeglądarka i CDN. CSS, JS, obrazy zapisane na urządzeniu odwiedzającego oraz w Cloudflare lub wybranym CDN.

Czyszczenie wszystkiego

Z poziomu panelu: Parametry zaawansowane → Wydajność → Wyczyść cache. Gdy sam panel nie działa:

# Wyczyszczenie katalogu cache bezpośrednio
rm -rf var/cache/prod/* var/cache/dev/*

# Lub użycie konsoli Symfony na PS 8+/9
php bin/console cache:clear --env=prod

OPcache

Po edycji plików PHP OPcache może nadal serwować stary kod bajtowy. Wywołanie opcache_reset() z poziomu CLI czyści tylko pulę CLI, a nie webową, są one rozdzielone. Niezawodny sposób: umieścić jednolinijkowy plik PHP, np. opcache.php, z treścią <?php opcache_reset();, otworzyć go w przeglądarce, a następnie usunąć.

Gdy cache się „zacina”

Należy dopasować warstwę cache do rodzaju zmiany:

• Edycja szablonów → Smarty
• Edycja kodu PHP → OPcache (reset webowy)
• Zmiany konfiguracji (services.yml, hooki) → Symfony
• CSS/JS → przeglądarka (Ctrl+Shift+R) i CDN
• „Class not found” → usunąć class_index.php

Po każdym wdrożeniu: cache Symfony, cache Smarty, OPcache (przez WWW/przeglądarkę, nie z CLI), CDN. Pominięcie któregokolwiek sprawi, że wdrożenie będzie wyglądać tak, jakby „nie zadziałało”. To najczęstsza przyczyna zgłoszeń „wdrożyliśmy, ale poprawki nie ma na żywo”, jakie obsługujemy.

6. Kłopoty z bazą danych

Problemy z bazą danych pojawiają się zwykle po nieudanej aktualizacji PrestaShop, przerwanym imporcie lub skrypcie zakończonym przekroczeniem czasu, który pozostawił połowę transakcji w bazie. Jeśli problemem jest rozrost, a nie uszkodzenie, warto zacząć od Database Cleanup lub równoważnego audytu SQL, zanim padnie podejrzenie na serwer.

Uszkodzone tabele

# Sprawdzenie wszystkiego
mysqlcheck -u root -p prestashop_db --check

# Naprawa (tylko MyISAM)
REPAIR TABLE ps_product;

# Dla InnoDB (którego używa każda nowoczesna instalacja) przebudowa w miejscu:
ALTER TABLE ps_product ENGINE=InnoDB;

Brakujące kolumny po nieudanej aktualizacji

Klasyczny błąd poaktualizacyjny: Unknown column 'new_column' in 'field list'. Skrypt aktualizacyjny przerwał działanie w połowie i pozostawił część tabel zmigrowanych połowicznie.

# Co faktycznie jest w tabeli
SHOW CREATE TABLE ps_product\G

# Sprawdzić install-dev/upgrade/sql/ lub install/upgrade/sql/ w poszukiwaniu skryptów aktualizacyjnych
# Dodać brakującą kolumnę ręcznie na ich podstawie:
ALTER TABLE ps_product ADD COLUMN `state` TINYINT(1) NOT NULL DEFAULT '1';

Porównywanie struktur

Gdy nie wiadomo, czego brakuje, warto zainstalować obok świeży PrestaShop w tej samej wersji, wykonać mysqldump --no-data dla obu baz danych i porównać. Każda brakująca tabela, kolumna i indeks wyłania się z porównania w dwie sekundy.

Zablokowane zapytania

SHOW FULL PROCESSLIST pozwala je znaleźć, KILL <id> zakończyć, a SHOW ENGINE INNODB STATUS przydaje się przy podejrzeniu oczekiwania na blokadę. Widzieliśmy, jak pojedyncze zablokowane zapytanie crona na ps_cart zaklinowało finalizację zamówienia w całym sklepie na czterdzieści minut, po zakończeniu zapytania sklep natychmiast się odblokował.

Nie należy uruchamiać ALTER TABLE na tabelach liczących wiele milionów wierszy w godzinach pracy sklepu. Widzieliśmy, jak całkowicie rozsądne zmiany schematu blokowały ps_product na dziesięć minut w ruchliwym sklepie, każda finalizacja zamówienia zawisała, dopóki operacja się nie zakończyła.

7. Problemy z motywem

Brakujące szablony

Błąd: unable to load template file 'module:modulename/...'. PrestaShop najpierw szuka w nadpisaniu motywu (themes/your_theme/modules/...) i dopiero gdy nadpisanie nie istnieje, sięga po własny szablon modułu. Jeśli nadpisanie motywu wskazuje na plik, który moduł zmienił lub usunął, pojawia się ten błąd. Należy też pamiętać: nazwy plików są w systemie Linux wrażliwe na wielkość liter, Header.tpl i header.tpl to różne pliki.

Błędy kompilacji Smarty

Trzy rzeczy, które obserwujemy najczęściej:

• Niesparowane znaczniki. Każdy {if} wymaga {/if}, każdy {foreach} wymaga {/foreach}.
• Nawiasy klamrowe w JavaScript. JS należy owinąć w {literal}...{/literal}, w przeciwnym razie Smarty spróbuje przetworzyć literały obiektów.
• Kodowanie. Pliki TPL muszą być w UTF-8 bez BOM. Sam BOM na początku pliku wystarczy, by zepsuć cały szablon.

Niewczytujące się zasoby

Należy otworzyć narzędzia deweloperskie, zakładkę Sieć i poszukać błędów 404. Zwykli podejrzani: błędne ścieżki w theme.yml, cache CCC, który nie przebudował się po wdrożeniu, lub CDN wskazujący na ścieżkę, która już nie istnieje.

Problemy z motywem potomnym

Usunięty motyw nadrzędny (potomny zgłasza „Invalid theme”), nieaktualne nadpisania szablonów po aktualizacji rodzica, która zmieniła szablony bazowe, lub brakujący wpis w pliku theme.yml motywu potomnego powodujący znikanie modułów z hooków. Nasze własne sklepy działają na potomku motywu Hummingbird i ta ostatnia sytuacja daje o sobie znać przy każdej aktualizacji PS.

Przed każdą aktualizacją PrestaShop warto przeczytać changelog pod kątem zmian w szablonach. Każde nadpisanie zmienionego szablonu w motywie potomnym wymaga przeglądu, czasem jednoliniowego scalenia, a czasem pełnego przepisania.

8. Zgodność wersji PHP

Zaskakująca część zgłoszeń „sklep się popsuł po aktualizacji hostingu” to po prostu rozjazd wersji PHP. Tabela zgodności:

* PS 1.7.8 ma częściowe wsparcie PHP 8.0. Rdzeń w większości działa, większość modułów firm trzecich nie.

Błędy zgłaszane na każdym etapie aktualizacji

• PHP 7.x → 8.0. TypeError: expects string, null given wszędzie. PHP 8 przestało po cichu rzutować null w strlen(), strpos() i pokrewnych.
• PHP 8.0 → 8.1. Return type should be compatible z powodu surowszych reguł dziedziczenia. FILTER_SANITIZE_STRING jest przestarzałe i zostanie usunięte, większość modułów nadal go używa.
• PHP 8.1 → 8.2. Dynamiczne właściwości przestarzałe. Każdy moduł, który ustawia $this->someThing = ... na klasie niedeklarującej tej właściwości, zapisuje ostrzeżenie.

Dwie rzeczy, o których warto wiedzieć w kontekście hostingu: wersje PHP dla CLI i serwera WWW mogą się różnić na serwerach z wieloma wersjami PHP, więc zawsze należy sprawdzać przez phpinfo() w przeglądarce, a nie tylko php -v w wierszu poleceń. Przed każdą aktualizacją produkcyjną warto przetestować na środowisku testowym, uruchomić php -l na każdym pliku modułu i najpierw zaktualizować moduły.

9. E-maile się nie wysyłają

• Test z panelu. Parametry zaawansowane → E-mail → „Wyślij testowy e-mail”. Wynik pokazuje, czy PrestaShop w ogóle potrafi porozumieć się ze swoim zapleczem pocztowym.
• Sprawdzić ustawienia SMTP. Host, port (587 dla TLS, 465 dla SSL), nazwa użytkownika, hasło.
• Sprawdzić tabelę ps_mail. Jeśli wiersze trafiają do tej tabeli, PrestaShop wysłał wiadomość. Problemem jest dostarczanie, a nie generowanie.
• Funkcja PHP mail() jest zawodna. Na każdym sklepie produkcyjnym warto przejść na SMTP. Jest bardziej niezawodny wszędzie i daje rzeczywistą diagnostykę dostarczania.
• SPF, DKIM, DMARC. Nowoczesne dostarczanie wymaga wszystkich trzech. Bez nich Gmail i Outlook po cichu odrzucą e-maile transakcyjne.
• Konkretnie potwierdzenia zamówień. Jeśli zamówienie istnieje, ale brakuje e-maila, Resend Order Confirmation daje obsłudze kontrolowaną ścieżkę ponownego wysłania po naprawieniu SMTP.

Pełny przewodnik: Dostarczalność e-maili w PrestaShop.

10. Sklep nagle zaczął działać wolno

Szybka diagnostyka

Należy sprawdzić dysk (df -h), obciążenie (uptime), MySQL (SHOW FULL PROCESSLIST) oraz stan OPcache. Pełny dysk po cichu rozkłada wszystko. MySQL nie może zapisywać, logi nie mogą się rotować, cache nie mogą się zapełniać.

Najczęstsze przyczyny, jakie obserwujemy

• Pozostawiony włączony tryb debugowania. Najpierw należy sprawdzić _PS_MODE_DEV_. Ta jedna linia rozwiązuje więcej zgłoszeń „sklep zwolnił” niż cokolwiek innego z tej listy.
• Pełny dysk. Nawet 95% zapełnienia wystarczy, MySQL potrzebuje zapasu, by zapisywać tabele tymczasowe.
• Jedno złe zapytanie modułu. Niezindeksowane zapytanie na dużej tabeli dodaje sekundy do każdej strony. Profiler Symfony (PS 8+) pokazuje czasy zapytań na każdej stronie.
• Nakładające się zadania crona. Dwa skrypty importu uruchomione w tym samym czasie i żaden nie zakończył się przed kolejnym taktem crona. Pliki blokad lub kolejka.
• Rozrośnięte tabele. ps_connections, ps_log, ps_cart, ps_guest rosną w nieskończoność, jeśli się ich nie przycina. Widzieliśmy ps_connections z 40 mln wierszy w sklepach, które nigdy ich nie czyściły.

Pełny przewodnik: Optymalizacja wydajności PrestaShop.

Jeśli spowolnienia wracają po sprawdzeniu podstaw, Performance Revolution to moduł, który zbudowaliśmy dokładnie do tego, profiluje kosztowne strony, hooki, moduły i zapytania wewnątrz sklepu. Warto go używać po sprawdzeniu logów i kondycji serwera, a nie zamiast nich.

11. Typowe komunikaty błędów, rozszyfrowane

„Class 'SomeClass' not found”

Należy usunąć var/cache/prod/class_index.php (regeneruje się przy kolejnym żądaniu), uruchomić composer dump-autoload na PS 1.7+ i sprawdzić wielkość liter w nazwie pliku w systemie Linux. Jeśli moduł został usunięty częściowo, trzeba będzie również posprzątać wiersze w ps_hook_module i ps_module.

„CSRF token error” / „Invalid token”

Wygasła sesja (zwiększyć session.gc_maxlifetime), wiele kart panelu walczących o tę samą sesję (odświeżyć), reverse proxy obcinające ciasteczka (wykluczyć panel z buforowania) lub (co bywa kłopotliwe) zegar serwera odjechał.

„Ajax error”

Należy otworzyć narzędzia deweloperskie, zakładkę Sieć i odtworzyć akcję. Nieudane żądanie (czerwone, status 500) będzie tam. Zakładka Odpowiedź zawiera faktyczny błąd PHP. Samo „Ajax error” nic nie mówi; leżąca u jego podstaw odpowiedź mówi zawsze.

„Allowed memory size exhausted”

Należy zwiększyć memory_limit = 512M. Jeśli sklep dalej pochłania coraz więcej, to wyciek pamięci w module, a profiler Symfony wskaże, w którym.

„Duplicate entry for key”

Naruszenie ograniczenia unikalności. Częste przy importach produktów (zduplikowane referencje), instalacjach modułów w trybie multistore trafiających w ten sam slug roli autoryzacji lub ponownym uruchomieniu aktualizacji, która poprzednio zakończyła się połowicznie.

„Deprecated: ...” zalewające logi

To ostrzeżenie, a nie błąd. Można je wyciszyć przez error_reporting = E_ALL & ~E_DEPRECATED, ale to prowizorka. Te ostrzeżenia są błędami krytycznymi w następnej wersji PHP. Zamiast tego należy zaktualizować moduł.

12. Awaryjne przywracanie

Reset hasła administratora

Jedyna metoda działająca we wszystkich wersjach PS: krótki skrypt PHP, który korzysta z własnej klasy haszującej PrestaShop. Należy go wgrać, uruchomić i natychmiast usunąć.

<?php
require __DIR__ . '/config/config.inc.php';
$crypto = new \PrestaShop\PrestaShop\Core\Crypto\Hashing();
$hash = $crypto->hash('YourNewPassword!');
Db::getInstance()->execute(
    "UPDATE ps_employee SET passwd = '" . pSQL($hash) . "' WHERE email = 'admin@yourdomain.com'"
);
echo "Password updated. DELETE THIS FILE NOW.\n";

Na PS 1.6 (które używało MD5 + klucza ciasteczka) należy zastosować to samo podejście, Tools::encrypt('YourNewPassword!') generuje poprawny hash dla tej wersji.

Skrypt resetujący należy usunąć w tej samej sekundzie, w której nastąpi zalogowanie. Każdy, kto go znajdzie, może zresetować dowolne hasło administratora w sklepie. Widzieliśmy takie skrypty pozostawione na działających sklepach przez lata.

Wyłączenie uszkodzonego modułu

-- Przez bazę danych
UPDATE ps_module SET active = 0 WHERE name = 'broken_module';

-- Przez system plików (bardziej niezawodne, zatrzymuje też uruchamianie hooka instalacji)
mv modules/broken_module modules/broken_module.disabled

Aby naraz wyłączyć każdy moduł firm trzecich, należy wykonać UPDATE ps_module SET active = 0 dla każdej nazwy, której nie ma na liście natywnych modułów PS (ps_banner, ps_categorytree, ps_facetedsearch itp.).

Wyłączenie override'ów

// config/defines.inc.php
define('_PS_ALLOW_OVERRIDES_', false);

Jedna flaga, każdy override pominięty. Gdy padnie podejrzenie na override'y, ale nie wiadomo na który, to przywraca sklep do życia na czas dochodzenia.

Przywracanie z kopii zapasowej

Należy wprowadzić sklep w tryb konserwacji, przywrócić bazę danych (mysql -u root -p db < backup.sql), przywrócić pliki, wyczyścić każdy cache (rm -rf var/cache/*), zresetować OPcache, a następnie przejść sklep od góry do dołu: strona główna, strona produktu, koszyk, finalizacja zamówienia, logowanie do panelu. Nie należy ufać przywróceniu, dopóki nie złoży się testowego zamówienia.

Tryb konserwacji, gdy panel jest uszkodzony

Tryb konserwacji w PrestaShop 8.

Przełącznik włącz/wyłącz, biała lista IP do testowego dostępu oraz niestandardowy komunikat konserwacji. Gdy trzeba wyłączyć sklep na czas napraw, to jest miejsce, w którym się to robi.

UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SHOP_ENABLE';
UPDATE ps_configuration SET value = 'your.ip' WHERE name = 'PS_MAINTENANCE_IP';

13. Lista kontrolna diagnostyki

Warto ją wydrukować. Pracować od góry do dołu. Nie pomijać kroków dlatego, że „wydają się oczywiste”.

Faza 1: zebranie informacji

• Co się zmieniło? Instalacja lub aktualizacja modułu, aktualizacja PS, aktualizacja PHP, zmiana na serwerze, edycja motywu?
• Kiedy dokładnie się zaczęło? Porównać z logami wdrożeń i znacznikami czasu crona.
• Kogo to dotyczy? Wszystkich, konkretnych przeglądarek, tylko panelu, tylko front office, tylko zalogowanych klientów?
• Jaki jest dokładny błąd? Tryb debugowania włączony, konsola przeglądarki otwarta, wszystkie logi sprawdzone.

Faza 2: izolacja

• Serwer: dysk (df -h), pamięć (free -m), CPU (top), MySQL (SHOW PROCESSLIST).
• PHP: wersja (php -v), składnia (php -l), konfiguracja na żywo (phpinfo()).
• Cache: wyczyścić każdą warstwę, Smarty, Symfony, OPcache, przeglądarka. Testować w trybie incognito.
• Moduły: wyłączyć najpierw najnowszy. Jeśli niejasne, wyłączyć wszystkie firm trzecich i włączać pojedynczo.
• Motyw: tymczasowo przełączyć na domyślny.
• Baza danych: mysqlcheck, log błędów MySQL, porównanie struktury przy podejrzeniu złej aktualizacji.
• Uprawnienia: ls -la na var/cache, var/logs, img, upload.

Faza 3: naprawa i weryfikacja

• JEDNA zmiana naraz. Przetestować. Jeśli nie naprawiła, cofnąć przed kolejną próbą.
• Wyczyścić wszystkie cache po każdej poprawce.
• Przejść sklep: strona główna, kategoria, produkt, koszyk, finalizacja zamówienia, panel.
• Testować w trybie incognito i w innej przeglądarce.
• Wyłączyć tryb debugowania. Usunąć wszelkie tymczasowe skrypty.

Faza 4: zapobieganie nawrotom

• Spisać, co się stało i co to naprawiło. Przyszłe „ja” podziękuje obecnemu „ja”.
• Skonfigurować monitoring: dostępność, logi błędów, miejsce na dysku.
• Zweryfikować kopie zapasowe, faktycznie przywracając jedną na środowisko testowe.

Szybkie odniesienie

Lokalizacje logów

• PS 1.6: log/ (PS 1.7: var/logs/) PS 8+/9: var/log/
• Apache: /var/log/apache2/error.log, Nginx: /var/log/nginx/error.log
• MySQL: /var/log/mysql/error.log, PHP: według error_log w php.ini

Kluczowe pliki

• config/defines.inc.php: przełącznik trybu debugowania, przełącznik override
• app/config/parameters.php: dane logowania do bazy, sekret (PS 1.7+)
• .env / .env.local: środowisko i flagi debugowania (PS 8+)
• .htaccess: przepisywanie adresów URL, ustawienia PHP, nagłówki bezpieczeństwa

Najważniejsze polecenia CLI (PS 1.7+)

php bin/console cache:clear --env=prod
php bin/console prestashop:module install module_name
php bin/console prestashop:module enable module_name
php bin/console prestashop:module disable module_name
php bin/console prestashop:module uninstall module_name
composer dump-autoload -o

Każda sesja rozwiązywania problemów zaczyna się tak samo: odczytać błąd, odczytać logi, wyizolować przyczynę. Doświadczeni deweloperzy nie zapamiętują każdego błędu, wiemy, gdzie szukać. Ta strona jest tą mapą.

Powiązane lektury

• Przewodnik po hookach PrestaShop: Display, Action i override: gdy problemem jest kolejność hooka lub konflikt override
• Motywy potomne PrestaShop: przewodnik po dostosowywaniu Classic i Hummingbird: czyste naprawianie nadpisań motywu
• Optymalizacja wydajności PrestaShop: przy wolnych stronach, kłopotach z cache i wąskich gardłach
• Dostarczalność e-maili w PrestaShop: SMTP, SPF, DKIM, DMARC, błędy dostarczania
• Przewodnik po hostingu PrestaShop: limity PHP, konfiguracja serwera, wymagania hostingowe
• Performance Revolution: profiler, po który sięgamy, gdy spowolnienia wciąż wracają

Powiązane pytania

• Jak włączyć tryb debugowania w PrestaShop?
• Konfiguracja modułu się nie zapisuje.
• Cache PrestaShop powoduje problemy. Czy powinienem go wyłączyć?
• Przypadkowo zepsułem plik .htaccess. Jak to naprawić?
• Moduł pokazuje błąd „Class not found” albo „Namespace not found”.
• Koszyk PrestaShop nie aktualizuje się: problemy z cache, JavaScript i konflikty modułów