Parempi WordPress-debuggaus Acornilla: WP_DEBUG-lukukelpoiseksi

WordPressin kehityksessä yksi helpoimmista tavoista säästää aikaa on pitää WP_DEBUG aina päällä lokaalissa ympäristössä. Se paljastaa notice-tason ongelmat ja varsinaiset fatal errorit heti — ja juuri ne “pienet” notice-varoitukset ovat usein niitä, jotka muuttuvat myöhemmin vaikeasti jäljitettäviksi bugeiksi tai yhteensopivuusongelmiksi muiden lisäosien kanssa.

Ongelma on, että WordPressin oletusdebuggaus on käytettävyydeltään aika karu: virheilmoitukset tulostetaan suoraan sivulle, eikä pino (stack trace) ole erityisen ystävällinen luettavaksi. Jos rakennat sivustoa Roots-stackilla (Bedrock + Acorn), saat tähän huomattavasti paremman kokemuksen käytännössä “kaupan päälle”.

Mitä WP_DEBUG käytännössä tekee (ja miksi se kannattaa pitää päällä)

WP_DEBUG on WordPressin debug-tila, joka aktivoidaan määrittelemällä WP_DEBUG-konstantti konfiguraatiossa. Kun se on päällä, WordPress näyttää ja/tai loggaa PHP-virheitä ja -huomautuksia. Kehitysympäristössä tämä on peruskauraa: saat välittömän palautteen deprecated-kutsuista, määrittelemättömistä muuttujista ja muista asioista, jotka muuten jäisivät piiloon.

Bedrockissa (Roots-projektin moderni WordPress-boilerplate, jossa riippuvuudet hoidetaan Composerilla) debug-tila on tyypillisesti valmiiksi päällä kehitysympäristöissä. Tämä on yksi Bedrockin käytännön hyödyistä: ympäristökohtainen konfiguraatio ohjaa asetuksia järkevästi ilman, että jokainen projekti keksii pyörää uudelleen.

WP_DEBUG:n oletusoutput: toimii, mutta ei ole mukava

Oletuksena WordPress puskee virheilmoitukset suoraan sivulle. Se on parempi kuin ei mitään, mutta käytännössä se tarkoittaa usein:

• Virhe näkyy kyllä, mutta konteksti (mistä se tuli ja miksi) jää vajaaksi.
• Stack trace on vaikea lukea, etenkin jos projekti käyttää moderneja rakenteita ja autoloadingia.
• Sama virheilmoitus voi toistua useaan kertaan ja sotkea näkymän nopeasti.

Lisäksi WordPress-ekosysteemissä on paljon lisäosia ja teemoja, jotka päästävät läpi notice- ja warning-tason viestejä. Kun teet omaa teemaa tai pluginia, nämä signaalit ovat arvokkaita: ne kertovat usein integraatio-ongelmista tai reunatapauksista, joihin törmäät vasta tuotannossa.

Acorn ja parempi error handling WordPressissä

Acorn on Roots-ekosysteemin PHP-sovelluskerros WordPressille, joka tuo Laravelista tuttuja käytäntöjä (esim. helperit, palvelukontit ja modernimpi sovellusrakenne) WordPress-projekteihin. Yksi konkreettinen hyöty arjessa on parempi virheenkäsittely, kun WP_DEBUG ja WP_DEBUG_DISPLAY ovat päällä.

Acornin oletus: Symfony exception handler

Acornin oletuskäytös on hyödyntää Symfonyn exception handleria. Käytännössä tämä tarkoittaa selkeämpää virhesivua: poikkeus, viesti ja pino esitetään huomattavasti luettavammin kuin WordPressin perusoutput.

Ignition: Laravel-tyylinen virhesivu myös WordPressiin

Jos olet tehnyt kehitystä Laravelilla, Ignition on todennäköisesti tuttu: se on Laravelin (v9:stä eteenpäin) oletusvirhesivu, jossa on todella hyvä developer experience. Acorn v3 toi mukanaan Laravelin reititystuen, ja samalla myös Ignition-tuki tuli mahdolliseksi WordPress-sivustoille, jotka käyttävät Acornia.

Ignition on erityisen hyödyllinen silloin, kun haluat nopean kokonaiskuvan: mitä tapahtui, missä tiedostossa, millä rivillä, ja miten koodi päätyi siihen. Se tekee virheiden “triagesta” huomattavasti nopeampaa.

Ignitionin saa käyttöön asentamalla sen kehitysriippuvuudeksi samassa hakemistossa, jossa Acorn on asennettuna:

composer require spatie/laravel-ignition --dev

composer require spatie/laravel-ignition --dev

Whoops (etenkin Acorn v2 -projekteissa)

Ennen Acorn v3:a tyypillinen suositus oli asentaa whoops (filp/whoops) parantamaan virhesivua. Jos pyörität vielä Acorn v2 -projektia, whoops voi edelleen tuoda selkeämmän virhenäkymän verrattuna Symfonyn perussivuun. Samalla kannattaa kuitenkin huomioida, että Acorn v3:ssa Ignition on se modernimpi ja luontevampi vaihtoehto.

Jos et käytä Acornia: kaksi käytännön vaihtoehtoa WP_DEBUG:n rinnalle

Kaikki projektit eivät ole Bedrock/Acorn-pohjaisia, ja välillä ympäristö on “perinteinen” WordPress. Silloinkin debuggausta voi parantaa ilman että koskee teema-arkkitehtuuriin. Kaksi laajasti käytettyä työkalua ovat:

• Query Monitor – monelle käytännössä pakollinen lokaalissa WordPress-kehityksessä: näyttää kyselyt, hookit, HTTP-kutsut, PHP-virheitä ja paljon muuta.
• Debug Bar – kevyt tapa tuoda debug-paneeli wp-adminiin ja tarkastella eri debug-tietoja.

Yhteenveto

1. Pidä WP_DEBUG aina päällä kehitysympäristössä, jotta huomaat virheet ja notice-varoitukset ajoissa.
2. WordPressin oletusdebug-näkymä on toimiva mutta vaikealukuinen, etenkin monimutkaisemmissa projekteissa.
3. Acorn parantaa WP_DEBUG-kokemusta: oletuksena Symfony exception handler, ja Acorn v3:ssa mahdollisuus käyttää Ignitionia.
4. Ignitionin saa käyttöön asentamalla spatie/laravel-ignition kehitysriippuvuudeksi Composerilla.
5. Ilman Acornia Query Monitor ja Debug Bar ovat hyviä tapoja parantaa debuggausta WordPressissä.