--- title: "Debugowanie WordPressa z Acorn: czytelne błędy zamiast surowego WP_DEBUG" url: "https://helloblog.io/pl/debugowanie-wordpressa-z-acorn-czytelne-bledy-zamiast-surowego-wp-debug/" date: "2023-02-14" modified: "2026-01-20" author: "Piotr Kowalski" language: "pl_PL" categories: ["Ekosystem WordPress"] tags: ["Acorn", "Bedrock", "Composer", "Debugowanie", "WordPress"] featured_image: "https://helloblog.io/app/uploads/sites/8/2026/01/featured-3-1024x572.png" excerpt: "Masz włączone \u0060WP_DEBUG\u0060, a mimo to diagnoza błędów w WordPressie dalej boli? Acorn potrafi zamienić surowe komunikaty PHP w czytelne strony wyjątków (Symfony/Ignition), które realnie przyspieszają pracę lokalnie." --- # 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. #### Instalacja Ignition (dev dependency) Ignition instalujesz przez Composer jako zależność developerską, uruchamiając polecenie w katalogu, w którym zainstalowany jest Acorn. ``` 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](https://querymonitor.com/) — absolutny must-have lokalnie: zapytania do bazy, hooki, HTTP requests, błędy PHP, cache i masa dodatkowych paneli diagnostycznych. - [Debug Bar](https://wordpress.org/plugins/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”. ## Odniesienia / Źródła - [Better WordPress Debugging with Acorn](https://roots.io/better-wordpress-debugging-with-acorn/) - [Bedrock](https://roots.io/bedrock/) - [Query Monitor](https://querymonitor.com/) - [Debug Bar](https://wordpress.org/plugins/debug-bar/) - [whoops](https://github.com/filp/whoops)