Tryb debugowania WordPressa. Jak włączyć zapis błędów do pliku i go odczytać?

Strona na WordPressie potrafi zepsuć się po cichu. Formularz przestaje wysyłać wiadomości, kokpit otwiera się co drugi raz, sklep gubi zamówienia, a na ekranie nie widać żadnego komunikatu albo widać tylko ogólne zdanie o błędzie krytycznym. W takiej chwili zgadywanie, która wtyczka zawiniła, zabiera godziny. Znacznie szybciej jest poprosić WordPressa, żeby sam zapisał, co poszło źle.

Do tego służy tryb debugowania. Po jego włączeniu system zapisuje błędy, ostrzeżenia i uwagi do zwykłego pliku tekstowego o nazwie debug.log. Każdy wpis wskazuje plik i numer wiersza, w którym pojawił się problem, więc zwykle od razu widać, czy źródłem jest wtyczka, motyw, czy własny fragment kodu.

Ta instrukcja jest przeznaczona dla właścicieli firm i osób opiekujących się stroną, które nie są programistami. Po lekturze będzie wiadomo, jak bezpiecznie włączyć zapis błędów do pliku, gdzie ten plik znaleźć, jak odczytać jego treść, co zrobić, gdy pozostaje pusty, jak ochronić go przed obcymi i jak wszystko wyłączyć po zakończeniu pracy.

Kiedy tryb debugowania jest potrzebny i co właściwie robi?

WordPress działa w języku PHP. Gdy w kodzie wtyczki, motywu albo samego systemu coś się nie zgadza, PHP zgłasza komunikat. Domyślnie większość takich komunikatów nie jest nigdzie pokazywana, a przy poważnej awarii odwiedzający widzi pustą stronę albo krótką informację o błędzie. To rozsądne ustawienie dla działającej witryny, ale przy szukaniu przyczyny niczego nie ułatwia.

Tryb debugowania zmienia to zachowanie. Dokumentacja WordPressa opisuje go jako zestaw ustawień, po których włączeniu zgłaszane są wszystkie błędy, ostrzeżenia i uwagi PHP, a dodatkowo informacje o przestarzałych funkcjach, które jeszcze działają, ale zostaną usunięte w kolejnych wersjach. Dokumentacja podkreśla też, że z tych opcji mogą korzystać osoby niebędące programistami, właśnie po to, aby zobaczyć szczegóły błędu.

Z mojego doświadczenia zapis do pliku przydaje się najczęściej w kilku sytuacjach:

• strona pokazuje biały ekran albo komunikat o błędzie krytycznym i nie wiadomo, co go wywołało,
• awaria pojawia się tylko czasami, na przykład raz na kilkanaście zamówień w sklepie,
• coś nie działa w tle: wysyłka wiadomości, zaplanowane publikacje, zapis w edytorze,
• po aktualizacji wtyczki albo motywu część funkcji przestała reagować,
• autor wtyczki lub firma hostingowa prosi o przesłanie treści błędu.

Zapis do pliku ma jedną dużą przewagę nad wyświetlaniem błędów na ekranie. Dziennik rejestruje także to, czego na ekranie nie widać, czyli zdarzenia z zapytań wykonywanych w tle i z zadań uruchamianych według harmonogramu. Dokumentacja wymienia tu wprost zapytania AJAX oraz przebiegi mechanizmu wp-cron.

Trzy ustawienia, które decydują o tym, gdzie trafiają błędy

Tryb debugowania włącza się w pliku wp-config.php, czyli w głównym pliku ustawień WordPressa. Wpisuje się tam tak zwane stałe, a więc krótkie wiersze z nazwą ustawienia i wartością. Do zapisu błędów w pliku potrzebne są trzy z nich i dobrze jest rozumieć każdą, zanim cokolwiek zostanie zmienione.

WP_DEBUG, czyli główny włącznik

Stała WP_DEBUG uruchamia tryb debugowania w całym WordPressie. Domyślnie ma wartość false, czyli tryb jest wyłączony. Dwie pozostałe stałe działają tylko wtedy, gdy ta jest ustawiona na true. To najczęstsza przyczyna pustego dziennika: ktoś włącza sam zapis do pliku, a główny włącznik zostaje wyłączony.

WP_DEBUG_LOG, czyli zapis do pliku

Stała WP_DEBUG_LOG sprawia, że wszystkie zgłoszenia trafiają dodatkowo do pliku. Przy wartości true WordPress zapisuje je w pliku debug.log w katalogu z treścią witryny, zwykle jest to wp-content/debug.log. Zamiast true da się podać pełną ścieżkę do innego pliku i wtedy dziennik powstanie we wskazanym miejscu. Ta druga możliwość jest dostępna od wersji 5.1 WordPressa.

WP_DEBUG_DISPLAY, czyli pokazywanie błędów na stronie

Stała WP_DEBUG_DISPLAY decyduje, czy komunikaty są wypisywane w treści strony. Jej wartość domyślna to true. Oznacza to, że samo włączenie trybu debugowania, bez tej stałej, pokaże komunikaty każdemu odwiedzającemu. Na działającej stronie firmowej trzeba ją zawsze ustawić na false, tak aby błędy trafiały wyłącznie do pliku.

W dokumentacji występują jeszcze dwie stałe: SCRIPT_DEBUG oraz SAVEQUERIES. Pierwsza wczytuje robocze wersje plików JavaScript i CSS samego WordPressa, a druga zapisuje wszystkie zapytania do bazy danych i według dokumentacji obniża wydajność. Obie są narzędziami dla programistów. Do ustalenia, co psuje stronę, nie są potrzebne i radzę ich nie włączać.

Co przygotować przed zmianą pliku wp-config.php?

Plik wp-config.php zawiera między innymi dane dostępu do bazy danych. Jeden brakujący średnik albo apostrof wystarczy, żeby cała witryna przestała się wczytywać. Dokumentacja WordPressa zaczyna opis debugowania od uwagi, że przed jakąkolwiek zmianą należy mieć kopię zapasową albo pracować na kopii testowej witryny. To nie jest formalność.

Przed rozpoczęciem pracy potrzebne są trzy rzeczy. Pierwsza to dostęp do plików witryny: menedżer plików w panelu hostingu albo program do połączeń FTP lub SFTP wraz z danymi logowania od firmy hostingowej. Druga to aktualna kopia całej strony, a jak ją przygotować i sprawdzić, opisałem we wpisie o tym, jak zrobić kopię zapasową WordPressa. Trzecia to osobna kopia samego pliku wp-config.php, pobrana na dysk komputera, do której da się wrócić w kilkanaście sekund.

Ważny jest też wybór programu do edycji. Plik należy otwierać w zwykłym edytorze tekstu, na przykład w Notatniku albo w edytorze wbudowanym w menedżer plików hostingu. Edytory dokumentów, takie jak Word, zamieniają proste apostrofy na ozdobne cudzysłowy, a po takiej zamianie PHP przestaje rozumieć wiersz.

Dokumentacja zaznacza, że narzędzia debugowania powstały z myślą o instalacjach lokalnych i testowych, a nie o stronach działających publicznie. W praktyce małe firmy rzadko mają kopię testową i awarię trzeba zbadać tam, gdzie występuje. Jest to dopuszczalne pod trzema warunkami: wyświetlanie błędów na ekranie pozostaje wyłączone, dziennik jest chroniony przed dostępem z zewnątrz, a tryb zostaje wyłączony zaraz po zebraniu informacji.

Jak włączyć zapis błędów do pliku?

Cała zmiana sprowadza się do wklejenia czterech wierszy w odpowiednim miejscu pliku wp-config.php. Poniższy zestaw pochodzi z oficjalnej dokumentacji WordPressa. Pominąłem w nim jedynie stałą SCRIPT_DEBUG, która jest potrzebna tylko przy zmienianiu plików samego systemu.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Pierwszy wiersz włącza tryb debugowania, drugi zapis do pliku debug.log, a trzeci i czwarty ukrywają komunikaty przed odwiedzającymi. Czynności wykonuje się w następującej kolejności:

1. Zalogowanie się do panelu hostingu i otwarcie menedżera plików albo połączenie z serwerem programem FTP lub SFTP.
2. Przejście do głównego katalogu WordPressa. To ten sam katalog, w którym znajdują się foldery wp-admin, wp-content i wp-includes.
3. Pobranie pliku wp-config.php na dysk komputera jako kopii, do której da się wrócić.
4. Otwarcie pliku wp-config.php w edytorze tekstu.
5. Wyszukanie w pliku słowa WP_DEBUG. W większości instalacji istnieje już wiersz define( 'WP_DEBUG', false );. Jeśli tak jest, należy w nim zmienić false na true, zamiast wklejać tę stałą po raz drugi.
6. Wklejenie pozostałych wierszy bezpośrednio pod wierszem ze stałą WP_DEBUG. Jeżeli tej stałej w pliku nie było, wkleja się wszystkie cztery wiersze powyżej wiersza z komentarzem /* That's all, stop editing! Happy blogging. */.
7. Zapisanie pliku pod tą samą nazwą i, przy pracy na kopii lokalnej, wysłanie go z powrotem na serwer w to samo miejsce.
8. Otwarcie strony głównej w przeglądarce i sprawdzenie, czy wczytuje się tak jak wcześniej.
9. Powtórzenie czynności, która wywołuje problem: wysłanie formularza, otwarcie kokpitu, złożenie próbnego zamówienia.

Miejsce wklejenia ma znaczenie. Dokumentacja zapisuje wielkimi literami, że wiersze muszą znaleźć się przed komentarzem kończącym część do edycji. W nowszych instalacjach ten komentarz może brzmieć nieco inaczej, a w polskiej wersji pliku bywa przetłumaczony, ale zawsze jest to wiersz informujący, że w tym miejscu kończy się edycja. Stałe wpisane poniżej są odczytywane za późno i nie mają żadnego skutku.

Wartości true i false wpisuje się bez apostrofów. Dokumentacja ostrzega, że zapis 'false' w apostrofach zostanie potraktowany jak true, ponieważ jest wtedy zwykłym tekstem, a nie wartością logiczną. Apostrofy obejmują wyłącznie nazwę stałej.

Jeśli po zapisaniu pliku strona przestała się wyświetlać, przyczyną jest prawie zawsze literówka: brak średnika na końcu wiersza, brak nawiasu albo ozdobny cudzysłów. Wystarczy wtedy wgrać na serwer pobraną wcześniej kopię pliku wp-config.php i wkleić wiersze jeszcze raz, tym razem bez przepisywania ich ręcznie.

Kto woli nie edytować plików na serwerze samodzielnie, może zadzwonić pod numer 533 525 168 albo napisać na info@lukaszwudyka.pl, a ja przejmę sprawę: włączę zapis błędów, odczytam dziennik i wskażę, który element strony powoduje awarię.

Gdzie leży plik debug.log i jak go otworzyć?

Plik nie powstaje w chwili włączenia trybu. WordPress tworzy go dopiero wtedy, gdy pojawi się pierwsze zgłoszenie do zapisania. Dlatego po zmianie ustawień trzeba odwiedzić stronę i wykonać czynność, która sprawia kłopot, a dopiero potem szukać dziennika.

1. Otwarcie menedżera plików albo połączenia FTP i przejście do głównego katalogu WordPressa.
2. Wejście do katalogu wp-content.
3. Odświeżenie listy plików. Programy FTP często pokazują zapamiętaną zawartość katalogu i bez odświeżenia nowy plik nie jest widoczny.
4. Odszukanie pliku o nazwie debug.log.
5. Pobranie pliku na dysk i otwarcie go w edytorze tekstu albo użycie podglądu w menedżerze plików hostingu.
6. Przewinięcie treści na sam koniec. Nowe wpisy są dopisywane na dole pliku, więc najświeższe zdarzenia znajdują się w ostatnich wierszach.

Przy dużym pliku dobrze sprawdza się prosty sposób: zapisanie bieżącej godziny, wywołanie błędu na stronie, a następnie odszukanie w dzienniku wpisów z tej minuty. Trzeba przy tym uwzględnić, że godziny w dzienniku WordPressa są zwykle podawane w czasie UTC, czyli różnią się od czasu obowiązującego w Polsce o godzinę albo dwie, zależnie od pory roku.

Jeżeli w stałej WP_DEBUG_LOG zamiast true została podana własna ścieżka, pliku należy szukać dokładnie w tym miejscu, a jego nazwa będzie taka, jaką wpisano. W katalogu wp-content niczego wtedy nie będzie.

Jak czytać wpisy w dzienniku?

Dziennik na pierwszy rzut oka wygląda groźnie, ale każdy wiersz ma tę samą, prostą budowę. Wystarczy umieć wyłowić z niego cztery informacje: kiedy, jak poważnie, co się stało i gdzie.

Z czego składa się pojedynczy wpis?

Typowy wiersz wygląda mniej więcej tak:

[data i godzina UTC] PHP Fatal error: Uncaught Error: Call to undefined function nazwa_funkcji() in /home/konto/public_html/wp-content/plugins/nazwa-wtyczki/includes/plik.php:128

W nawiasie kwadratowym stoi data i godzina zdarzenia. Dalej znajduje się rodzaj zgłoszenia, tutaj „PHP Fatal error”. Potem następuje opis po angielsku, a na końcu ścieżka do pliku i numer wiersza, podany po dwukropku albo po słowach „on line”. Przy błędach krytycznych pod wpisem często pojawia się jeszcze blok „Stack trace” z ponumerowanymi wierszami. Pokazuje on, jakie pliki były wywoływane po kolei, zanim doszło do awarii.

Które rodzaje zgłoszeń są groźne, a które nie?

Rodzaj zgłoszenia mówi, jak pilna jest sprawa. Nie każdy wiersz w dzienniku oznacza usterkę widoczną dla klienta.

• „PHP Fatal error” i „PHP Parse error” to błędy, które przerywają działanie strony albo jej części. To one stoją za białym ekranem i komunikatem o błędzie krytycznym, więc szuka się ich w pierwszej kolejności.
• „PHP Warning” oznacza ostrzeżenie. Strona działa dalej, ale jakaś funkcja mogła nie wykonać swojego zadania, na przykład nie odczytała pliku albo nie wysłała wiadomości.
• „PHP Notice” to uwaga o niedbałym, lecz działającym kodzie. Dokumentacja wyjaśnia, że takie komunikaty dotyczą często rzeczy, które nie wyglądają na zepsute.
• „PHP Deprecated” informuje o użyciu przestarzałej funkcji. Nic się nie psuje, ale autor wtyczki lub motywu powinien poprawić kod przed kolejnymi wersjami PHP i WordPressa.

Jak ustalić, co zawiniło?

Odpowiedź kryje się w ścieżce do pliku. Fragment wp-content/plugins/nazwa-wtyczki/ wskazuje konkretną wtyczkę, a nazwa katalogu odpowiada jej nazwie technicznej. Fragment wp-content/themes/nazwa-motywu/ wskazuje motyw. Ścieżka prowadząca do katalogów wp-includes albo wp-admin oznacza pliki samego WordPressa, choć w takim przypadku przyczyną bywa wtyczka, która błędnie wywołała funkcję systemu. Wtedy winowajcę zdradza blok „Stack trace”, w którym nazwa wtyczki pojawia się kilka wierszy niżej.

Znając winowajcę, wyłącza się daną wtyczkę w kokpicie na ekranie „Wtyczki” i powtarza czynność, która wywoływała problem. Jeśli kokpit jest niedostępny, wystarczy zmienić przez FTP nazwę katalogu tej wtyczki, co powoduje jej wyłączenie. Cały tok postępowania przy takiej awarii opisałem osobno we wpisie o komunikacie „W witrynie wystąpił błąd krytyczny”.

Nie należy poprawiać kodu wtyczki ani motywu na własną rękę we wskazanym wierszu. Taka zmiana zniknie przy najbliższej aktualizacji, a nieumiejętna może pogorszyć sytuację. Właściwa droga to aktualizacja do najnowszej wersji, a gdy to nie pomaga, zgłoszenie błędu autorowi z załączonym fragmentem dziennika albo zastąpienie wtyczki inną.

Co oznaczają najczęstsze komunikaty?

Kilka opisów powtarza się w dziennikach szczególnie często. „Call to undefined function” oznacza, że kod wywołuje funkcję, której nie ma, zwykle dlatego, że wymagana wtyczka została wyłączona albo wersje do siebie nie pasują. „Allowed memory size exhausted” to wyczerpany limit pamięci PHP. „Maximum execution time exceeded” oznacza, że skrypt działał dłużej, niż pozwala serwer. „Cannot modify header information – headers already sent” pojawia się najczęściej wtedy, gdy w którymś pliku PHP znalazł się zbędny znak przed kodem albo po nim.

Najwygodniej jest skopiować opis błędu bez ścieżki i wkleić go w wyszukiwarkę razem z nazwą wtyczki. Popularne błędy są zazwyczaj opisane na forum pomocy danej wtyczki wraz z rozwiązaniem.

Po czym poznać, że problem został naprawiony?

Samo zniknięcie objawu na ekranie nie jest jeszcze dowodem. Błąd, który pojawiał się nieregularnie, może po prostu nie wystąpić przez kilka godzin. Dlatego przed wyłączeniem trybu debugowania warto wykonać prostą próbę kontrolną.

Polega ona na tym, że po wprowadzeniu poprawki, na przykład po aktualizacji albo wyłączeniu wadliwej wtyczki, stary dziennik pobiera się na dysk i kasuje z serwera. Następnie kilkakrotnie powtarza się czynność, która wcześniej wywoływała awarię, i sprawdza, czy plik debug.log powstał na nowo. Jeżeli nie ma go wcale albo nie zawiera wierszy „PHP Fatal error” związanych z badanym elementem, naprawa zadziałała.

Gdy ten sam wpis nadal się pojawia, poprawka nie objęła właściwego miejsca. Trzeba wtedy porównać ścieżkę z nowego wpisu ze ścieżką z poprzedniego. Inna ścieżka oznacza drugi, niezależny błąd, który wcześniej był przesłonięty pierwszym. Ta sama ścieżka oznacza, że wskazany element wciąż jest aktywny albo że działa jego kopia zapisana w pamięci podręcznej.

Jeżeli dziennik jest czysty, a strona nadal zachowuje się niewłaściwie, przyczyna leży poza kodem PHP. W grę wchodzą wtedy ustawienia serwera, baza danych albo skrypty działające w przeglądarce.

Plik debug.log jest pusty albo nie powstaje. Co sprawdzić?

Brak pliku nie zawsze oznacza usterkę w ustawieniach. Jeśli od włączenia trybu nie wystąpiło żadne zgłoszenie, WordPress nie ma czego zapisać. Gdy jednak problem na stronie się powtarza, a dziennika nadal nie ma, należy po kolei sprawdzić poniższe przyczyny.

• Stała WP_DEBUG ma nadal wartość false. Bez głównego włącznika zapis do pliku nie działa.
• Stała została wpisana dwa razy. Jeśli wyżej w pliku pozostał stary wiersz z wartością false, to on obowiązuje, a drugi jest pomijany. W pliku ma zostać jedna definicja każdej stałej.
• Wiersze znalazły się poniżej komentarza kończącego część do edycji. Trzeba je przenieść wyżej.
• Edytowany był niewłaściwy plik. Na serwerze bywa kilka kopii WordPressa, na przykład stara wersja strony w podkatalogu. Właściwy jest plik z katalogu, z którego naprawdę działa witryna.
• Serwer nie może zapisywać w katalogu wp-content. O uprawnienia do zapisu należy zapytać firmę hostingową albo sprawdzić je w panelu.
• Hosting kieruje błędy PHP do własnego dziennika i nie pozwala zmienić tego ustawienia z poziomu witryny. Wtedy zapisów trzeba szukać w panelu hostingu, w części poświęconej dziennikom błędów.
• Strona jest podawana z pamięci podręcznej. Odwiedzający dostaje gotową kopię, PHP się nie uruchamia i błąd nie ma kiedy wystąpić. Na czas badania należy wyczyścić pamięć podręczną albo sprawdzać stronę po zalogowaniu.
• Błąd powstaje poza PHP. Dziennik WordPressa nie rejestruje usterek skryptów działających w przeglądarce ani awarii samego serwera.

Ostatni punkt wymaga rozwinięcia. Jeżeli przycisk na stronie nie reaguje, a w dzienniku nic się nie pojawia, przyczyna może leżeć w kodzie JavaScript, który wykonuje się na komputerze odwiedzającego. Takie błędy widać w konsoli przeglądarki, a nie w pliku debug.log. Z kolei awarie zgłaszane przez serwer, zanim WordPress w ogóle się uruchomi, trafiają do dziennika błędów serwera. Dotyczy to także literówki w samym pliku wp-config.php. Więcej o szukaniu przyczyny w takich przypadkach napisałem we wpisie o tym, jak ustalić przyczynę błędu 500.

Ustawienia da się też potwierdzić bez zaglądania do plików. W kokpicie należy otworzyć „Narzędzia”, a następnie „Stan witryny” i przejść do zakładki „Informacje”. W części poświęconej stałym WordPressa widać aktualne wartości ustawień debugowania, czyli to, co system faktycznie odczytał z pliku wp-config.php.

Jak zabezpieczyć dziennik przed obcymi?

To najważniejsza część całej instrukcji i jednocześnie ta, którą najczęściej się pomija. Katalog wp-content jest dostępny z internetu, bo leżą w nim zdjęcia i pliki motywu. Plik debug.log zapisany w tym katalogu ma przewidywalny adres i na wielu serwerach każdy, kto ten adres wpisze w przeglądarce, zobaczy jego treść.

W dzienniku znajdują się pełne ścieżki na serwerze, nazwy i wersje wtyczek, a czasem także fragmenty zapytań do bazy danych, adresy e-mail lub dane z formularzy. Dla osoby szukającej słabych punktów witryny to gotowa mapa. WordPress sam o tym przypomina: na ekranie „Stan witryny”, w zakładce „Status”, pojawia się ostrzeżenie, że witryna zapisuje błędy do pliku, który może być publicznie dostępny.

Jak sprawdzić, czy plik jest widoczny z zewnątrz?

Wystarczy otworzyć w przeglądarce okno prywatne i wpisać adres złożony z nazwy domeny oraz ścieżki /wp-content/debug.log. Jeżeli przeglądarka pokaże treść dziennika albo zacznie go pobierać, plik jest dostępny dla każdego. Komunikat o braku dostępu albo o nieznalezionej stronie oznacza, że serwer go chroni.

Najpewniejsza metoda: dziennik poza katalogiem publicznym

Dokumentacja pliku wp-config.php zaleca, aby dzienniki trzymać powyżej katalogu publicznego, czyli w miejscu, do którego nie prowadzi żaden adres internetowy. Służy do tego druga forma stałej, z pełną ścieżką zamiast wartości true:

define( 'WP_DEBUG_LOG', '/home/konto/logi/wp-bledy.log' );

Ścieżka w przykładzie jest umowna. Właściwą trzeba ustalić dla własnego serwera: w menedżerze plików należy wyjść o jeden poziom wyżej niż katalog ze stroną, zwykle nazwany public_html albo podobnie, utworzyć tam katalog na dzienniki i przepisać jego pełną ścieżkę. Serwer musi mieć prawo zapisu w tym katalogu. W razie wątpliwości pełną ścieżkę poda firma hostingowa.

Blokada dostępu, gdy plik zostaje w wp-content

Na serwerach Apache i zgodnych z nim, które odczytują pliki .htaccess, da się zablokować dostęp do samego dziennika. W pliku .htaccess w głównym katalogu witryny, poza blokiem oznaczonym jako należący do WordPressa, dopisuje się taki fragment:

<Files "debug.log">
Require all denied
</Files>

Przed zmianą trzeba pobrać kopię pliku .htaccess, ponieważ błąd w jego składni wyłącza całą stronę. Po zapisaniu należy ponownie wykonać próbę w oknie prywatnym. Serwery Nginx nie odczytują plików .htaccess, więc na nich ta metoda nie zadziała i pozostaje ścieżka poza katalogiem publicznym albo prośba do hostingu o dodanie reguły.

Niezależnie od wybranej metody obowiązuje prosta zasada: dziennik nie powinien leżeć na serwerze dłużej, niż trwa szukanie przyczyny. Im krócej istnieje, tym mniejsze ryzyko.

Jak wyłączyć debugowanie po zakończeniu pracy?

Tryb debugowania pozostawiony na stałe szkodzi na dwa sposoby. Dziennik rośnie bez ograniczeń, bo WordPress sam go nie czyści ani nie dzieli na części, i z czasem potrafi zająć znaczną część miejsca na koncie hostingowym. Do tego w pliku gromadzi się coraz więcej informacji o budowie witryny. Po ustaleniu przyczyny awarii należy więc wszystko przywrócić.

1. Otwarcie pliku wp-config.php w edytorze tekstu, tak samo jak przy włączaniu.
2. Zmiana wartości w wierszu ze stałą WP_DEBUG z true na false. Po tej zmianie wiersz ma postać define( 'WP_DEBUG', false );.
3. Usunięcie wierszy ze stałymi WP_DEBUG_LOG i WP_DEBUG_DISPLAY oraz wiersza z display_errors albo pozostawienie ich bez zmian. Przy wyłączonym głównym włączniku nie mają one żadnego skutku.
4. Zapisanie pliku i sprawdzenie, czy strona wczytuje się poprawnie.
5. Pobranie pliku debug.log na dysk, jeśli jego treść ma zostać przekazana autorowi wtyczki lub firmie hostingowej.
6. Skasowanie pliku debug.log z serwera.
7. Otwarcie w kokpicie ekranu „Stan witryny” i sprawdzenie w zakładce „Status”, czy zniknęło ostrzeżenie dotyczące zapisu błędów.

Dobrym potwierdzeniem jest także ponowna próba otwarcia adresu dziennika w oknie prywatnym. Tym razem przeglądarka powinna pokazać informację o nieznalezionej stronie.

Przed wysłaniem dziennika komukolwiek radzę go przejrzeć. Do zgłoszenia wystarcza zwykle kilkanaście wierszy z chwili awarii, razem z blokiem „Stack trace”. Całego pliku nie trzeba publikować na forum, tym bardziej że widać w nim ścieżki serwera i nazwę konta.

Jakich błędów unikać przy debugowaniu?

Większość kłopotów z trybem debugowania nie wynika z samego narzędzia, lecz z pośpiechu. Poniższe pomyłki widuję najczęściej.

• Włączenie samej stałej WP_DEBUG na działającej stronie. Komunikaty wyświetlają się wtedy wszystkim odwiedzającym, razem ze ścieżkami na serwerze.
• Edycja pliku wp-config.php bez kopii. Jedna literówka i witryna przestaje działać, a nie ma do czego wrócić.
• Pozostawienie trybu włączonego po zakończeniu pracy i zapomnienie o pliku, który rośnie przez kolejne miesiące.
• Wklejanie całego dziennika na publiczne forum albo do grupy dyskusyjnej.
• Uznanie każdego wiersza za awarię. Uwagi i informacje o przestarzałych funkcjach nie wymagają natychmiastowej reakcji.
• Kasowanie wtyczek zamiast ich wyłączania. Skasowanie może usunąć także ustawienia i dane, a do sprawdzenia przyczyny wystarcza wyłączenie.
• Poprawianie kodu cudzej wtyczki bezpośrednio na serwerze, bez wiedzy o tym, co dany wiersz robi.

Uważam, że tryb debugowania najlepiej traktować jak przegląd w warsztacie: włącza się go w konkretnym celu, zbiera informacje, a potem wyłącza. Stałe nasłuchiwanie błędów na stronie firmowej ma sens tylko wtedy, gdy ktoś ten dziennik regularnie czyta i gdy plik leży poza katalogiem publicznym.

Najczęstsze pytania

Czy tryb debugowania spowalnia stronę?

Sam zapis błędów do pliku ma niewielki wpływ na szybkość, o ile zgłoszeń nie jest bardzo dużo. Wyraźnie obciąża witrynę stała SAVEQUERIES, o czym ostrzega dokumentacja, dlatego nie należy jej włączać bez potrzeby. Większym kłopotem niż szybkość jest rozmiar dziennika, który przy wielu zgłoszeniach rośnie z każdą odsłoną strony.

Czy da się włączyć debugowanie bez dostępu do FTP?

Potrzebny jest jakikolwiek sposób edycji pliku wp-config.php. Zwykle wystarcza menedżer plików w panelu hostingu, który działa w przeglądarce i nie wymaga osobnego programu. Istnieją także wtyczki, które zmieniają te ustawienia z poziomu kokpitu, ale przy awarii kokpit bywa niedostępny, więc dostęp do plików i tak trzeba mieć przygotowany.

Strona pokazuje błąd krytyczny, a WordPress wysłał wiadomość e-mail. Czy dziennik jest wtedy potrzebny?

Od wersji 5.2 WordPress ma tryb odzyskiwania, który przy błędzie krytycznym wtyczki lub motywu pokazuje komunikat zamiast białego ekranu i wysyła administratorowi wiadomość z odnośnikiem do bezpiecznego logowania. Często to wystarcza, bo wiadomość wskazuje element, który zawiódł. Dziennik przydaje się wtedy, gdy wiadomość nie dotarła, gdy błąd nie jest krytyczny albo gdy pojawia się nieregularnie. Jak postępować przy pustej stronie, opisałem we wpisie o tym, jak naprawić biały ekran w WordPressie.

W dzienniku są setki wierszy „PHP Deprecated”. Czy strona jest zepsuta?

Nie. Takie wpisy oznaczają, że wtyczka lub motyw korzysta z funkcji przewidzianych do usunięcia w przyszłości. Strona działa normalnie, a jedynym zaleceniem jest aktualizacja danego elementu do najnowszej wersji. Jeżeli wpisy nie znikają po aktualizacji, dobrze jest zgłosić je autorowi, ponieważ przy kolejnej zmianie wersji PHP mogą zamienić się w prawdziwe błędy.

Dlaczego godziny w dzienniku nie zgadzają się z zegarem?

WordPress prowadzi wewnętrzne obliczenia w czasie UTC i w takim czasie zapisywane są zwykle wpisy dziennika. Czas w Polsce jest przesunięty względem UTC o godzinę zimą i o dwie godziny latem. Przy szukaniu konkretnego zdarzenia trzeba więc odjąć odpowiednią liczbę godzin od czasu z zegara.

Czy błędy da się wyświetlić na ekranie zamiast w pliku?

Tak, wystarczy pozostawić stałą WP_DEBUG_DISPLAY z wartością domyślną. Ma to sens wyłącznie na kopii testowej albo lokalnej, do której nie mają dostępu klienci. Nawet wtedy komunikaty nie pojawią się przy zapytaniach AJAX, REST i XML-RPC, ponieważ WordPress nigdy nie wyświetla błędów w odpowiedziach na takie zapytania. Plik pokazuje więc pełniejszy obraz.

Brak czasu albo ochoty, żeby zająć się tym samodzielnie?

Praca z plikami na serwerze nie każdemu sprawia przyjemność i wcale nie musi. Chętnie zajmę się tym od początku do końca: wykonam kopię, włączę zapis błędów w bezpieczny sposób, odtworzę awarię, przeczytam dziennik i wyjaśnię prostymi słowami, co zawiodło i dlaczego. Potem naprawię przyczynę albo wskażę, do kogo należy ją zgłosić, a na koniec wyłączę tryb debugowania i uprzątnę pliki, tak aby na serwerze nie został żaden ślad dostępny dla obcych.

Wystarczy zadzwonić pod numer 533 525 168 albo napisać na adres info@lukaszwudyka.pl i opisać w kilku zdaniach, co dzieje się ze stroną. Odpowiem, czego potrzebuję, żeby zacząć, i ile to potrwa.