WordPress Debuggen – Handige tools voor de WP Developer

Tools die je als WordPress Developer uren tijd kunnen besparen

Nadat ik begonnen ben code snippets op de WordXPression site te plaatsen kreeg ik behoorlijk wat vragen van mensen die met deze snippets aan de gang gingen, maar toch niet helemaal de gewenste resultaten kregen. Ondanks het feit, dat de code snippets zijn getest, zijn veel van de code snippets voor specifieke situaties en kan je in jouw geval een aantal dingen net iets anders moeten doen, om het voor jou ook te laten werken. Wanneer je geen of minder ervaring met PHP hebt -de programmeertaal waar WordPress mee werkt- kan het lastig zijn de door jouw gemaakte fout te vinden. En zelfs wanneer je die wel hebt, dan kun je je soms blindstaren op een heel kleine fout.

In dit artikel wil ik je een aantal foutsituaties laten zien en -nog veel belangrijker- leren hoe je deze foutsituaties kan identificeren en corrigeren. En voor dat ‘identificeren’ hebben we een aantal handige tools.

Maar eerst – voor jet aan WordPress debuggen kan beginnen – moet je natuurlijk kunnen zien dat er fouten zijn!

Er heeft zich een fout voorgedaan!

Wanneer jouw WordPress goed geïnstalleerd en geconfigureerd is, dan zal je geen foutboodschappen krijgen. Tenminste niet op je scherm. Er kunnen zich twee situaties voordoen. Je krijgt een geheel blanco scherm, of je krijgt een scherm met de boodschap, dat er zich een fout heeft voorgedaan, en de foutboodschap is verstuurd naar het email adres van de contactpersoon van de website.

Wanneer je een foutboodschap ziet, dan geeft de verzonden email vaak meer informatie over de fout zelf. Heb je een blanco scherm is het sterk afhankelijk van de instellingen van je hosting partij welke informatie er is weggeschreven in een zogenaamde ‘errorlog’. Hier gaan we later op in.

Het zoeken naar en oplossen van fouten wordt ‘debuggen’ genoemd. Het ‘verwijderen van beestjes’. De oorsprong van deze naam is uit de tijd dat computers nog voor een groot gedeelte uit buizen bestonden en deze buizen soms voortijdig doorbrandden, omdat er een vliegje was geland op het hete glas. Het letterlijk verwijderen van ‘beestjes’ dus.

Wil aan de slag gaan met het debuggen van je website, doe je dit slechts in zeldzame gevallen op je live omgeving. Normaal gesproken doe je dit om een aantal redenen op een staging omgeving. Er is een klein aantal gevallen te bedenken, wanneer je het toch op een livesite zou doen.

Het beschikbaar maken van debug informatie

De reden dat WordPress de debug informatie niet direct op het scherm zet, is omdat dit aanwijzingen voor eventuele hackers kunnen zijn voor de zwakke plaatsen in je website. Bovendien is in zo’n foutmelding vaak ook informatie te vinden over de exacte fysieke locatie op de harddisk van jouw WordPress installatie, wat ook weer kostbare informatie voor een eventuele hacker is.

Je kan deze foutinformatie direct op je scherm krijgen, wanneer je -zoals eerder genoemd, liefst in een staging omgeving- ‘debuggen’ aanzet door in je wp-config.php bestand op zoek te gaan naar een regel met de tekst

define('WP_DEBUG' , false);

hier verander je de ‘false’ in ’true’, dus

define('WP_DEBUG' , true);

Komt deze regel niet voor, voeg deze regel dan toe net boven de regel

/* That's all, stop editing! Happy publishing */

Vergeet niet dit direct na je debug acties weer terug naar de waarde false te zetten.

Vanaf nu worden alle foutmeldingen naar je scherm gestuurd en zie je deze gelijk.

De debug log gebruiken

Dat loggen naar een scherm is goed voor het ontdekken van ‘brekende fouten’, fouten waarbij het systeem niet meer verder kan. Maar soms zijn de ware schuldigen niet de ‘brekende fouten’, maar fouten die ontstaan zijn door eerdere fouten.

Het kan handig zijn om hier goed zicht op te krijgen door de fouten niet op het scherm te zetten, maar naar een errorlog te schrijven. Bij de meeste hosting partijen gebeurd dit al vanzelf, raadpleeg de documentatie van je hosting partij waar je de ‘errorlog’ kan vinden. Soms wordt die errorlog zelfs in een handige viewer getoond, waarbij je ook nog eens kan filteren op IP adres. Wat wel handig is, omdat op een drukke website het anders wel een enorme hoeveelheid informatie wordt.

Je kan ook expliciet een errorlog via WordPress laten maken. Om de foutmeldingen niet naar je beeldscherm, maar naar een bestand te krijgen, vul je op de plaats waar je de ‘debug regel’ vond, de volgende drie regels in :

define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY' false);
define('WP_DEBUG_LOG', true);

De foutmeldingen worden nu weggeschreven naar een bestand ‘debug.log’ in je wp-content folder.

Wat kan ik met die debug informatie?

Laten we even uitgaan van de situatie waarin jij zelf een codefragment hebt toegevoegd aan WordPress. Bijvoorbeeld één van de snippets hier op de WordXPression site. Een mogelijke fout zou er als volgt uit kunnen zien

Een fout van het type E_PARSE werd veroorzaakt op regelnummer 156 van het bestand /home/customer/www/willekeurigewebsite.nl/public_html/wp-content/plugins/wxp-support-functions/index.php. Foutmelding: syntax error, unexpected '}'

Wat kan ik hier zoal in teruglezen? Allereerst, dat de fout zich heeft voorgedaan in het lezen van het bestand index.php van een plugin met de naam ‘wxp-support-functions’. En wel op regelnummer 156.

Het is een ‘PARSE’ fout, ofwel een fout waarbij PHP zegt, dat het bestand geen juiste PHP is, PHP kan het niet lezen. En het kan niet worden gelezen, omdat er ergens een ‘}’ staat waar deze niet wordt verwacht. (een ‘}’ moet altijd door een ‘{‘ worden voorafgegaan.

Debug Bar

Debug Bar is een plugin van WordPress.org zelf. Het is een eenvoudige, maar krachtige plugin die alleen geactiveerd wordt wanneer je

1. De plugin hebt geïnstalleerd
2. De plugin hebt geactiveerd
3. en sinds 1 en 2 normaal is voor een plugin, weet, dat je om de plugin ook werkelijk actief te maken, je ook de wp-config.php file aan moet passen.

Aan de wp-config.php file kan je twee opties activeren. Let er op, dat je dit altijd in een staging omgeving doet! De Debug Bar moet je niet op een live omgeving gebruiken.

<?php
define('WP_DEBUG', true) //zorgt ervoor dat alle meldingen, niet alleen de foutmeldingen worden afgevangen
define('SAVEQUERIES', true) // alle verzoeken naar de database worden geregistreerd. 

Zolang de plugin actief is, zullen alle foutmeldingen via de Debug Bar worden afgehandeld. Maar zodra je de plugin deactiveert en de ‘wp-config.php’ niet aanpast, zullen foutmeldingen naar het scherm worden gestuurd. En dat wil je niet.

Daarom is het beter deze plugin uitsluitend op staging en ontwikkel sites te gebruiken.

Query Monitor

Query Monitor is één van mijn favoriete speeltjes en ik raad iedere WordPress Professional aan deze plugin te gebruiken zodra je aan de gang moet gaan met ’trouble shooting’.

Oorspronkelijk was Query Monitor uitsluitend een plugin voor het monitoren van vragen richting database. Omdat WordPress een extreem database intensief CRM is, en ‘database vragen’ gewoonlijk de meeste tijd kosten, was het belangrijk voor ontwikkelaars om te weten hoe ‘snel’ verschillende opties om gegevens uit een database op te vragen voor WordPress waren. Dit was informatie die heel moeilijk te verkrijgen was voor mensen die geen ‘performance expert’ voor MySQL -de database achter WordPress- waren.

Inmiddels is Query Monitor uitgegroeid tot een veel complexere plugin met veel meer gebruiksmogelijkheden. Eigenlijk is het een ‘monitor’, die alles bijhoudt wat er gebeurt op het moment dat er een pagina wordt geladen. De foutmeldingen, de onderdelen die het meeste tijd kosten, de database queries, de onnodige herhalingen van functieaanroepen.

Kortom, een onmisbare tool voor iedere WordPress Developer die de tijd wil nemen om deze plugin goed te willen leren kennen.

Onderdeel van Query Monitor is ook de eerder genoemde ‘Debug Bar’. Alle functionaliteit die in Debug Bar zit, vind je ook in Query Monitor en het aardige is, dat er voor Debug Bar een groot aantal extensies is gemaakt, die probleemloos samenwerken met Query Monitor.

Eén die ik in het bijzonder naar voren wil halen -omdat ik zelf veel met Elementor werk- is de ‘Elementor’ Extension die gemaakt is voor Debug Bar, maar ook prima werkt met Query Monitor.

Een makkelijkere optie voor het debuggen van Elementor templates is wanneer je in je Dashboard gaat naar Elementor -> Extra. Onder de tab ‘Algemeen’ vind je de optie ‘Foutopsporingsbalk’.

Wanneer je deze inschakelt, krijg je behoorlijk wat extra informatie voor je Elementor pagina’s.

Query Monitor is een vrij resource intensieve plugin en zal jouw ervaring met je website absoluut enorm vertragen. Wanneer jij als Admin met ingelogd, worden er zoveel extra processen opgestart, dat je site -in jouw ervaring- stukken langzamer wordt.

Het is dus goed deze plugin te deactiveren, wanneer je hem niet expliciet gebruikt.

Verre van ideaal

Deze methoden van foutzoeken zijn prima wanneer je te maken krijgt met fouten die de programmaflow onderbreken, die een acute stop veroorzaken. Deze methode is goed geschikt om bijvoorbeeld een conflict tussen plugins te ontdekken. Wanneer je zelf iets in WordPress ontwikkeld, of het nu een snippet, plugin of thema is, dan heb je hier onvoldoende gereedschap aan. Want je hebt niet alleen te maken met brekende fouten, maar ook met logische fouten.

Kijk eens naar het codefragment in PHP hieronder

<?php 

$x = 0

if ($x=1) {
    echo "Dit zou je nooit verwachten te zien"; 
} 

Als leek zou je misschien hier lezen, dat $x -een variabele- de waarde 0 krijgt, en je daarna kijkt of $x de waarde 1 heeft. Wat natuurlijk niet het geval is… En ALS $x de waarde 1 heeft, dan print je die regel. Maar aangezien je hebt gezegd, dat $x gelijk aan 0 is, zie je die regel nooit.

Hier is alleen een denkfout gemaakt. In PHP wordt = namelijk niet voor vergelijkingen, daar gebruik je == voor.

Wanneer ik zeg if ($x=1), dan gebeurt er iets wat weinig intuitief is, maar wel zo werkt in de meeste programmeertalen. Eerst zal het statement tussen de haakjes worden geëvalueerd. en $x=1, wil zeggen, ‘ken $x de waarde 1’ toe. En aangezien dat altijd lukt. krijg je altijd die waarde te zien.

De juiste code zou zijn geweest

<?php 

$x = 0

if ($x==1) {
    echo "Dit zou je nooit verwachten te zien"; 
} 

Je begrijpt natuurlijk, dat beide codefragmenten allebei goed zijn, in die zin, dat ze geen fout in de uitvoering van het programma veroorzaken. Maar ze geven niet allebei het verwachte resultaat.

En dit soort fouten zijn lastiger te vinden. Maar laten we daar ook eens verder induiken.

Xdebug – De klassieke PHP Debugger

Zolang ik zelf met PHP werk -en dat is lang, ik ben hier in 2000 mee begonnen- bestaat Xdebug al. Xdebug is een PHP extensie die geïnstalleerd moet worden binnen de PHP-service op de server. Door middel van een ‘client’ in een lokaal programma kan je dan regel voor regel meekijken in de code terwijl deze stapsgewijs wordt uitgevoerd.

De meeste moderne PHP IDE’s (Integrated Development Environment) bieden een dergelijke ondersteuning voor Xdebug aan. En wanneer je een locale PHP omgeving als bijvoorbeeld LocalWP installeert is Xdebug aan de server-kant een onderdeel van de installatie.

De twee meest populaire code editors voor PHP, PHPStorm (betaald) en VS-Code (gratis) bieden ook ondersteuning door middel van een client integratie met Xdebug.

Voor het debuggen van WordPress is Xdebug echter niet de meest geschikte debugger. Eén van de krachtige kenmerken van WordPress zorgt er ook voor, dat debuggen met Xdebug toch vrij tijdrovend kan zijn. En dat heeft alles te maken met de ‘hooks’ van WordPress. de ‘aangrijppunten’ in de WordPress programmatuur, waardoor plugins in staat zijn om op de juiste momenten code uit te voeren.

Wanneer je stap voor stap de code wilt doorlopen, kom je al snel terecht in een warwinkel van ‘hooks’ die het debuggen niet echt makkelijker maken.

Een tweede nadeel van Xdebug is dat dit een manier van debuggen is, die alleen vanaf een goed beveiligde server kan. Xdebug installeren op een server die publiek toegankelijk is, is een veiligheidsrisico, omdat in principe iedereen de site in debug mode aan kan roepen.

Xdebug is een krachtige tool. Maar voor mij eerder een ‘laatste redmiddel’ wanneer ik er echt niet uitkom, dan mijn ‘eerste keuze’.

Meest populaire oplossing – var_dump.

Voor de meeste PHP programmeurs hun toevlucht nemen tot Xdebug maken ze voor WordPress debuggen eerst gebruik van de interne PHP functie ‘var_dump’ of ‘var_export’. Het verschil tussen beide functies is het output formaat.

Zie de verschillen in het voorbeeld hieronder

<?php 
$vlag = array('rood', 'wit', 'blauw');
echo var_dump($vlag);  
//uitvoer: array(3) { [0]=> string(4) "rood" [1]=> string(3) "wit" [2]=> string(5) "blauw" }

echo var_export($vlag); 
//uitvoer: array ( 0 => 'rood', 1 => 'wit', 2 => 'blauw', )

Om te voorkomen dat je debug code hebt toegevoegd die later wordt ‘meegenomen’ naar een livesite is het altijd goed om er een test omheen te zetten, waardoor de code alleen in debug mode wordt getoond. Dus iets als :

<?php 
$vlag = arrau('rood', 'wit', 'blauw');

if (WP_DEBUG) {
   echo var_dump($vlag);
}

Uitdagingen met var_dump

Output via de var_dump functie worden direct op het scherm geplaatst, het programma loopt gewoon door. En dat is een beetje problematisch, wanneer de verdere loop van het programma een compleet scherm op gaat bouwen. Dan zie je even in een flits je output verschijnen… om vervolgens te zien hoe dat onder het werkelijke scherm verdwijnt.

Wat de meeste programmeurs dan ook doen is direct na de ‘var_dump’ functie een ‘die’ functie aan te roepen.

Het codefragment ziet er dan ongeveer als volgt uit:

<?php
echo var_dump($post);
die();

Omdat dit een vrij gebruikelijke opeenvolging van handelingen is, hebben veel programmeurs een ‘uility functie’ in hun eigen functies bestand met een definitie voor een ‘dd’ functie, die staat voor ‘dump and die’.

Wanneer je éénmalig de functie ‘dd’ definieert als

<?php
function dd($param) {
   echo var_dump($param);
   die();
}

kan je voortaan volstaan met

<?php
dd($param);

Maar wanneer je stap voor stap op een dergelijke wijze door je debugging proces heen moet lopen, is dit opnieuw behoorlijk tijdrovend.

Ray – Een straaltje zonlicht

Ik werk al jaren met WordPress maar tot twee jaar terug had ik nog nooit van Ray gehoord. En dat is ook niet zo vreemd, omdat Ray, een totaal ander soort debugger dan gebruikelijk, ook nooit voor WordPress geschreven was. Oorspronkelijk.

De problemen die er zijn om WordPress met een klassieke debugger als Xdebug van fouten te ontdoen zijn nog veel meer van toepassing wanneer je Laravel moet debuggen. Gelukkig was er iemand op het lichtende idee gekomen om een totaal ander soort debugger te schrijven. Ray. En origineel was Ray ook uitsluitend voor Laravel bedoeld, maar inmiddels wordt een groot aantal andere platforms en talen ondersteund.

Ray is een desktop applicatie voor Windows of Mac waarmee je een verbinding maakt met je webplatform. En op het moment dat ik dit schrijf kan je Ray gebruiken voor onder meer de volgende platforms:

PHP based

• ‘Standaard’ PHP
• Laravel
• Craft CMS
• Drupal
• Yii
• WordPress

Javascript based

• Standaard JavaScript
• Alpine.js
• Vue.js
• React
• Node.js
• Express

Overige talen

• Bash
• Go
• Ruby

Het idee is eenvoudig. Voor alle genoemde talen is er een module beschikbaar die je op de server kan activeren. Voor WordPress is het de Ray plugin.

Met de desktop applicatie leg je contact met de website.

Vanuit de website kan je door middel van specifiek ‘ray’ functies debug informatie versturen naar je desktop applicatie. Het werkt dus ongeveer net zo als de ‘php_dump’ functie, maar je scherm wordt niet vervuild door debug informatie. Die komt in een apart scherm.

De ray() basisfunctie.

Wanneer je al gewerkt hebt met var_dump(), dan is ray() niet veel anders. Je kunt aan de ‘ray’ functie iedere gewenste variabele meegeven, die vervolgens in de desktop console getoond zal worden.

Maar je kan veel meer dan alleen de waarden van variabelen laten zien.

Hieronder enkele voorbeelden:

<?php 
ray('Hello World');

zal in de console het volgende laten zien:

Wat hier ziet is dus het tijdstip van de output, de output en een positie in de code, waar deze output van afkomstig is (web.php, regel 22). Wanneer je bij Ray de door jouw gebruikte editor instelt, dan wordt bij een klik op de ‘web.php:22’ regel de editor op deze coderegel geopend.

Geef ik een coderegel in als

<?php
ray(['a' => 1, 'b' => 2])->color('red');

dan is de output iets als:

Door de methode ‘color(‘red’)’ aan te roepen, wordt deze output van een rood label voorzien. Dit is handig, omdat je de output ook kan filteren op label-kleur.

Een tweede handigheid in de output zie je in de naar beneden wijzende driehoek bij de array inhoud. Als ik daarop klik ‘klapt’ het array dicht. Bij complexe structuren als geneste arrays en objecten behoud je zo het overzicht.

Een aantal andere handige functies die je kan gebruiken zijn

ray()->showQueries() en ray()->stopShowingQueries()

Wanneer je de eerste functie aanroept, zullen alle vraagstellingen in de richting van de database worden getoond, inclusief de executietijd. Wanneer je de tweede functie aanroept, stopt dit.

ray()->showWordPressErrors() en ray()->shopShowingWordPressErrors()

Na het aanroepen van de eerste functie worden alle foutmeldingen naar de ray console gestuurd, na het aanroepen van de tweede stop dit.

ray()->showHooks() en ray()->stopShowingHooks()

Dit is met name een nuttige functie, wanneer je een overzicht wilt hebben van alle ‘hooks’ die aanroepbaar zijn in de code. Dit kan soms uren zoekwerk door code en documentatie schelen.

Het fraaie van Ray is ook, dat in een productieomgeving de ray() functies het niet zullen doen, tenzij je eerst ray()->enable() aanroept. Je kan dus veilig je ‘debug code’ in de broncode laten staan.

TinkerWell

Een ander handig hulpmiddel vanuit het Laravel Ecosystem is TinkerWell. Hoewel TinkerWell primair voor Laravel ontwikkeld is, biedt TinkerWell ook ondersteuning voor WordPress. Net zoals Ray is ook TinkerWell een desktop programma.

TinkerWell is geen ‘debugger’ in de traditionele zin van het woord. Het is een gereedschap om ‘dingen even uit te proberen’. Of zoals de makers het omschrijven, een ‘PHP Scratchpad’, een PHP Kladblok.

Wat TinkerWell doet, is binnen de context van een WordPress omgeving een mogelijkheid te geven PHP code uit te laten voeren.

Dat kan om een aantal redenen heel handig zijn:

Het opbouwen van een Query-object
De juiste manier om in WordPress posts op te halen om verder te verwerken is via een zogenaamd ‘Query object‘. Om posts in te lezen wordt een dergelijk object aangemaakt, met een vrij complexe structuur voor het filteren van de juiste posts.

Soms kan die structuur zo complex zijn, dat je even een ’test plaatsje’ wilt hebben om het uit te proberen. Het testen of de juiste gegevens worden opgevraagd kan vrij complex zijn, wanneer je dit binnen WordPress zelf op de ‘klassieke’ manier wilt testen. Binnen TinkerWell is dit veel eenvoudiger en meer interactief.

Database manipulaties via de WordPress API

Stel je wilt voor een performance test 10.000 gebruikers toevoegen aan de database. Je kan hier een script voor schrijven, maar dan moet je toch behoorlijk wat extra code toevoegen om de WordPress omgeving voor te laden.

In TinkerWell kan je iets eenvoudigs intikken als

<?php
for ($i = 0; $i < 10000; $i++) {  
   wp_create_user(uniqid(),    
                  wp_generate_password(12, false),    
                  uniqid().'@example.com'  
    );
}

en op de TinkerWell ‘run’ button klikken, en de gebruikers zijn toegevoegd.

Het maken en testen van code snippets

In samenwerking met Ray om de juiste hooks te vinden, is TinkerWell ideaal om code snippets te testen. Natuurlijk is de uiteindelijke test een praktijktest, maar omdat je bij TinkerWell direct de resultaten van de functie kan zien, hoef je niet bij iedere test eerst de stappen te zien of het werkt.

Of het laten maken van code snippets met AI

Tinkerwell heeft integratiemogelijkheden met ChatGPT en wanneer je jouw ChatGPT API key hebt tegevoegd, kan je met normale (engelstalige) vragen code snippets genereren en testen. Denk erom, enige eigen interpretatie van de code blijft noodzakelijk.

Ten slotte

In dit artikel heb je een aantal manieren kunnen lezen die je kan gebruiken om WordPress te debuggen. Goed testen en debuggen is nodig om kwaliteitscode op te kunnen leveren. Heb jij interesse om WordPress developer te worden, dan heeft WordXPression de juiste cursus voor je. Tweemaal per jaar beginnen we met een nieuw traject. Eén van de onderdelen van de cursus is het leren debuggen.