Debugowanie WordPressa z Acorn: czytelne błędy zamiast surowego WP_DEBUG

W WordPressie debugowanie zwykle zaczyna się i kończy na stałej WP_DEBUG. I słusznie — lokalnie to powinien być absolutny standard, bo pozwala szybko wyłapać notice, warning i błędy, które w innym przypadku potrafią ukrywać się tygodniami. Problem w tym, że domyślny output WordPressa jest… mało przyjazny. W praktyce dostajesz zrzut komunikatu na ekran, często bez kontekstu, bez ładnego stack trace i bez sensownej prezentacji danych.

Jeśli budujesz projekty na stacku Roots (np. Bedrock + Acorn), możesz to znacząco poprawić. Acorn — czyli warstwa integrująca sporą część ekosystemu Laravel z WordPressem — potrafi podmienić obsługę wyjątków i wyświetlać błędy w formie, do której przyzwyczaiły nas nowoczesne frameworki PHP.

WP_DEBUG w praktyce: co daje i dlaczego warto go mieć zawsze lokalnie

WP_DEBUG to przełącznik trybu debug w WordPressie. Po jego włączeniu WordPress i PHP zaczynają raportować m.in. błędy, ostrzeżenia i notatki (notices), które często sygnalizują problemy jakościowe w kodzie: użycie nieistniejącej zmiennej, wywołanie przestarzałej funkcji, nieprawidłowy typ argumentu itp.

W projektach opartych o Bedrock (nowoczesny boilerplate WordPressa zarządzany przez Composer) tryb debug w środowisku developerskim jest już sensownie ustawiony domyślnie — dzięki osobnym plikom konfiguracyjnym per środowisko. To oszczędza czas i ogranicza ryzyko, że ktoś „zapomni” o debugowaniu lokalnie.

Dlaczego domyślny output WP_DEBUG bywa niewystarczający

WordPress w najprostszym wariancie wyświetla komunikat bezpośrednio na stronie. To lepsze niż cisza, ale przy realnych błędach (zwłaszcza w złożonych motywach i wtyczkach) szybko pojawiają się typowe problemy:

• mało czytelny stack trace albo jego brak (zależnie od kontekstu i konfiguracji PHP)
• trudno znaleźć źródło błędu w kodzie, gdy wyjątek wypływa głęboko z hooków WordPressa
• brak dodatkowego kontekstu w stylu „co to za request”, „jakie były dane wejściowe”, „co jest w zmiennych”

W efekcie debugowanie zamienia się w ręczne dorzucanie error_log(), var_dump() albo w bieganie z Xdebug — co jest OK, ale nie zawsze najszybsze na start.

Co zmienia Acorn: lepsza obsługa wyjątków przy WP_DEBUG

Acorn poprawia doświadczenie debugowania, gdy masz aktywne WP_DEBUG oraz WP_DEBUG_DISPLAY. Innymi słowy: gdy WordPress ma debugować i ma prawo coś wyświetlić w przeglądarce, Acorn przejmuje obsługę wyjątków i pokazuje je w czytelniejszej formie.

Warto doprecyzować pojęcia: exception handler (obsługa wyjątków) to komponent, który decyduje jak aplikacja reaguje na wyjątki — czy tylko je loguje, czy zwraca HTML, jaki pokazuje stack trace, jak formatuje dane itd. WordPress historycznie nie był projektowany jako framework aplikacyjny, więc jego domyślna ergonomia w tym obszarze jest ograniczona.

Domyślne strony błędów w Acorn: handler Symfony

Domyślnie Acorn wykorzystuje mechanizm obsługi wyjątków z ekosystemu Symfony. W praktyce oznacza to bardziej uporządkowaną stronę błędu: czytelny komunikat, plik i linia, oraz stack trace, który da się normalnie przejrzeć.

Ignition w WordPressie (Acorn v3): doświadczenie jak w Laravelu

Jeśli pracujesz z Laravelem, Ignition prawdopodobnie kojarzysz jako domyślną stronę błędu w Laravelu (od wersji 9). W Acorn v3 pojawiło się wsparcie dla routingu w stylu Laravel, a razem z nim możliwość używania Ignition także w projektach WordPressowych opartych o Acorn.

To jest duża zmiana jakościowa, bo Ignition jest nastawiony na szybkie namierzanie problemów: prezentuje wyjątek w bardzo czytelnej formie i ułatwia nawigację po stack trace. Jeśli zależy Ci na możliwie „frameworkowym” DX (developer experience) w WordPressie, to jest najrozsądniejsza opcja.

composer require spatie/laravel-ignition --dev

composer require spatie/laravel-ignition --dev

Po instalacji, przy włączonym WP_DEBUG i WP_DEBUG_DISPLAY, błędy powinny zacząć renderować się z użyciem Ignition (zgodnie z konfiguracją Acorn). Szczegóły konfiguracji i zachowania są opisane w dokumentacji Roots w sekcji error handling.

Whoops: starsza, ale nadal użyteczna alternatywa

Przed Acorn v3 popularnym uzupełnieniem był whoops (biblioteka PHP do ładnych stron błędów). Jeśli z jakiegoś powodu siedzisz jeszcze na Acorn v2, whoops nadal potrafi poprawić czytelność wyjątków względem bazowego outputu.

W praktyce: jeśli masz możliwość, sensowniejszy jest upgrade do Acorn v3 i wejście w Ignition, ale whoops bywa dobrym krokiem pośrednim tam, gdzie modernizacja jest blokowana przez kompatybilność projektu.

A jeśli nie używasz Acorn? Dwie wtyczki, które robią robotę

Acorn nie jest jedyną drogą do lepszego debugowania. Jeśli pracujesz na „klasycznym” WordPressie (bez Bedrock/Acorn), są wtyczki, które świetnie uzupełniają codzienną diagnostykę:

• Query Monitor — absolutny must-have lokalnie: zapytania do bazy, hooki, HTTP requests, błędy PHP, cache i masa dodatkowych paneli diagnostycznych.
• Debug Bar — prostszy zestaw narzędzi, ale nadal przydatny, gdy chcesz szybki podgląd podstawowych informacji debug.

Jak to poukładać w projekcie: sensowny baseline dla zespołu

Jeśli chcesz, żeby debugowanie było konsekwentne w całym zespole, dobrze działa takie podejście:

1. Lokalnie zawsze włącz WP_DEBUG (w Bedrocku ustawienia per środowisko ułatwiają temat).
2. Trzymaj WP_DEBUG_DISPLAY włączone tylko tam, gdzie to ma sens (najczęściej lokalnie), żeby błędy nie „wyciekały” na staging/produkcję.
3. Jeśli projekt stoi na Acorn v3: dołóż Ignition jako --dev i traktuj to jako standard DX.
4. Niezależnie od Acorn: miej pod ręką Query Monitor do analizy wydajności i problemów z hookami/zapytaniami.

Podsumowanie

WP_DEBUG to fundament, ale w czystym WordPressie jego output jest daleki od ideału. Acorn poprawia ten obszar, przejmując obsługę wyjątków i podając błędy w formie znanej z nowoczesnych aplikacji PHP. W Acorn v3 szczególnie warto zwrócić uwagę na Ignition — to jedna z tych zmian, które realnie skracają czas od „mamy błąd” do „wiem dokładnie gdzie i dlaczego”.