WP_DEBUG — jak bezpiecznie włączyć logowanie błędów WordPressa?

WP_DEBUG pomaga ujawnić ostrzeżenia i błędy kodu, ale nie powinien zamieniać publicznej strony w ekran pełen ścieżek serwera. Bezpieczna diagnostyka zapisuje komunikaty do chronionego logu, ukrywa je przed odwiedzającymi, trwa możliwie krótko i kończy się usunięciem przyczyny oraz wyłączeniem trybu.

Krótka odpowiedź: wykonaj kopię wp-config.php, najlepiej pracuj na stagingu, ustaw WP_DEBUG na wartość logiczną true, włącz WP_DEBUG_LOG, a WP_DEBUG_DISPLAY ustaw na false. Dodaj definicje przed komentarzem kończącym edycję pliku. Odtwórz błąd raz, pobierz właściwy fragment logu, potem przywróć WP_DEBUG do false i usuń publicznie dostępny log. Nie wpisuj 'false' w cudzysłowie — jako niepusty tekst może zostać potraktowany jak prawda.

Kiedy WP_DEBUG jest właściwym narzędziem?

Użyj go, gdy diagnozujesz:

• krytyczny błąd po aktualizacji;
• biały ekran lub odpowiedź 500 generowaną przez PHP;
• ostrzeżenia motywu albo wtyczki;
• problem wykonywany poza widocznym ekranem, np. AJAX lub WP-Cron;
• niezgodność z nową wersją PHP;
• problem możliwy do powtórzenia na stagingu.

Nie pomoże bezpośrednio, jeśli żądanie zatrzymuje się przed uruchomieniem WordPressa: na DNS, CDN, regule Apache, braku pliku albo awarii usługi PHP. Wtedy potrzebujesz logu właściwej warstwy.

Zanim zmienisz wp-config.php

1. Wykonaj bieżącą kopię pliku oraz pełny backup strony.
2. Sprawdź, czy masz sposób cofnięcia zmiany przez SFTP lub panel plików.
3. Zapisz dokładny objaw, URL i godzinę.
4. Jeśli to możliwe, odtwórz problem na stagingu.
5. Upewnij się, że edytujesz konfigurację właściwej instalacji.

Błąd składni w wp-config.php może wyłączyć całą stronę. Nie używaj edytora, który zmienia apostrofy na typograficzne albo dodaje ukryte formatowanie.

Bezpieczna konfiguracja zapisu do logu

W pliku wp-config.php, przed linią w rodzaju /* That's all, stop editing! Happy blogging. */, ustaw:

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

Znaczenie ustawień:

• WP_DEBUG aktywuje tryb diagnostyczny WordPressa;
• WP_DEBUG_LOG zapisuje komunikaty domyślnie do wp-content/debug.log;
• WP_DEBUG_DISPLAY steruje pokazywaniem ich w HTML;
• display_errors dodatkowo prosi PHP, aby nie wyświetlało błędów użytkownikowi.

Oficjalna dokumentacja WordPressa zaleca narzędzia debugowania głównie dla kopii deweloperskich i stagingowych, nie jako stałe ustawienie produkcji.

Najczęstszy błąd: zduplikowane definicje

Przed dodaniem kodu wyszukaj istniejące WP_DEBUG, WP_DEBUG_LOG i WP_DEBUG_DISPLAY. Nie dopisuj drugiego zestawu na końcu pliku. Stała PHP nie powinna być definiowana ponownie, a sprzeczne wartości utrudniają rozpoznanie faktycznego stanu.

Poprawnie:

define( 'WP_DEBUG', false );

Niepoprawnie:

define( 'WP_DEBUG', 'false' );

Druga wartość jest tekstem, nie wartością logiczną. Niepusty tekst może zachowywać się jak true.

Jak zapisać log poza publicznym katalogiem?

WordPress pozwala podać prawidłową ścieżkę zamiast true, np.:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/bezpieczna/sciezka/wp-errors.log' );
define( 'WP_DEBUG_DISPLAY', false );

Ścieżka zależy od hostingu. Katalog musi istnieć i być zapisywalny dla procesu PHP, ale nie powinien być publicznie dostępny. Nie kopiuj przykładowej ścieżki bez dostosowania. Jeśli nie znasz układu serwera, poproś hosting o właściwe miejsce.

Jak przeprowadzić kontrolowany test?

1. Wyczyść lub oznacz moment rozpoczęcia testu bez niszczenia wcześniejszych dowodów.
2. Otwórz dokładny URL albo wykonaj jedno działanie wywołujące problem.
3. Zapisz godzinę i odpowiedź przeglądarki.
4. Pobierz debug.log lub log ze wskazanej ścieżki.
5. Odszukaj wpisy z tego samego czasu.
6. Zabezpiecz kopię fragmentu przed wprowadzaniem naprawy.

Jeżeli plik się nie tworzy, sprawdź:

• czy WP_DEBUG naprawdę ma wartość logiczną true;
• czy kod znajduje się przed komentarzem końcowym;
• czy nie ma duplikatu definicji;
• czy katalog jest zapisywalny;
• czy problem dociera do WordPressa;
• czy hosting nie przechwytuje błędów do własnego logu PHP;
• czy test rzeczywiście wywołał komunikat.

Brak debug.log nie oznacza, że strona nie ma błędu.

Co oznaczają wpisy?

Nie reaguj na każdą linię tak samo. Fatal error lub nieobsłużony wyjątek może przerwać żądanie. Warning wskazuje problem, ale kod często działa dalej. Notice albo deprecated ostrzega o niepoprawnej lub wycofywanej praktyce.

Szukaj wpisu zgodnego z czasem testu i objawem. Zanotuj:

• typ błędu;
• komunikat;
• pierwszy plik należący do motywu, wtyczki albo własnego kodu;
• numer linii;
• stos wywołań;
• wersje WordPressa, PHP i komponentu;
• zmianę wykonaną bezpośrednio przed awarią.

Nazwa wtyczki w stosie jest hipotezą, nie wyrokiem. Potwierdź ją na stagingu.

Czego nie włączać automatycznie?

SCRIPT_DEBUG ładuje deweloperskie, niezminimalizowane wersje skryptów i stylów rdzenia. Nie jest potrzebny do zwykłej diagnozy błędu PHP.

SAVEQUERIES zapisuje informacje o zapytaniach do bazy i może zwiększać zużycie pamięci. Używaj go tylko w kontrolowanej diagnozie wydajności.

Nie zostawiaj też własnych funkcji masowo zapisujących całe obiekty, treść formularzy lub dane użytkowników. Logowanie ma być minimalne i celowe.

Jak wyłączyć diagnostykę po teście?

Przywróć:

define( 'WP_DEBUG', false );

Usuń albo wyłącz towarzyszące ustawienia zgodnie z przyjętą konfiguracją. Następnie:

• sprawdź stronę i panel;
• zabezpiecz potrzebny fragment logu;
• usuń debug.log z publicznego katalogu, jeżeli nie jest już potrzebny;
• sprawdź, czy plik nie jest osiągalny przez HTTP;
• zapisz przyczynę, naprawę i wynik testu;
• monitoruj, czy błąd nie wraca.

WP_DEBUG na produkcji — tylko jako krótka, kontrolowana operacja

Jeśli problemu nie da się odtworzyć poza produkcją, przygotuj okno diagnostyczne. Ukryj wyświetlanie błędów, ogranicz czas, monitoruj rozmiar pliku i nie wykonuj testu w szczycie. Przy serwisie przetwarzającym zamówienia lub dane wrażliwe zaangażuj administratora.

Najbezpieczniejszy WP_DEBUG to ten, który odpowiada na konkretne pytanie, zapisuje możliwie mało danych i zostaje wyłączony natychmiast po zebraniu dowodu.