WP_DEBUG aanzetten zonder dat je bezoekers de foutmeldingen zien

Je site geeft een witte pagina. Of een blok verschijnt niet, een formulier doet niks, en er staat nergens een foutmelding. WordPress slikt fouten standaard in, want een bezoeker heeft niets te maken met een PHP-waarschuwing over regel 214.

Handig voor bezoekers, onhandig voor jou. WP_DEBUG zet dat gordijn open.

De drie regels die je nodig hebt

Open wp-config.php en zoek de regel define( 'WP_DEBUG', false );. Die staat er al. Vervang hem door dit blok:

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

Wat elke regel doet:

• WP_DEBUG zet het rapporteren van fouten aan. Zonder deze staat de rest uit.
• WP_DEBUG_LOG schrijft alles weg naar een bestand.
• WP_DEBUG_DISPLAY op false houdt de meldingen van het scherm af.
• De ini_set is de vangnetregel. Sommige hosts negeren WP_DEBUG_DISPLAY en tonen fouten alsnog.

Die combinatie is het hele punt. Zet je alleen WP_DEBUG aan, dan verschijnen de waarschuwingen boven aan je pagina. Op een live site kijkt een bezoeker dan tegen je bestandspaden aan, en die verraden meer dan je denkt.

De volgorde is belangrijk. Alles moet boven de regel /* That's all, stop editing! */ staan, anders is WordPress al geladen en gebeurt er niks.

Waar het logbestand staat

Standaard komt het in wp-content/debug.log. Dat bestand wordt aangemaakt zodra er iets te loggen valt, dus zie je het niet, dan is er nog niets misgegaan.

Nu het punt waar de meeste mensen overheen lezen: die map is gewoon via de browser bereikbaar. Iedereen die jouwsite.nl/wp-content/debug.log intikt leest mee. En in zo’n log staan bestandspaden, tabelnamen en soms stukken query.

Zet hem daarom ergens anders neer:

define( 'WP_DEBUG_LOG', dirname( ABSPATH ) . '/logs/debug.log' );

Dat is een map naast je webroot, buiten het bereik van de browser. De map moet wel bestaan en schrijfbaar zijn, anders krijg je stilletjes geen log.

Het log lezen zonder te verzuipen

Een debug.log van een drukke site groeit hard. Openen in een editor werkt niet meer zodra hij een paar megabyte is. Heb je SSH, dan is dit je beste vriend:

tail -f wp-content/debug.log

Het log loopt nu live mee. Laat dat venster openstaan, klik in een ander venster de handeling aan die misgaat, en je ziet precies wat erbij hoort. Veel prettiger dan achteraf zoeken tussen duizend regels.

Wil je alleen de echte problemen zien en niet elke deprecated-melding:

tail -f wp-content/debug.log | grep -i "fatal error"

Begin je fris, gooi het bestand dan eerst leeg met > wp-content/debug.log. Scheelt scrollen.

Zelf iets in het log zetten

Zoek je waar een waarde onderweg verandert, dan schrijf je hem gewoon zelf weg:

error_log( print_r( $order_data, true ) );

Dat werkt met arrays en objecten. Handiger dan var_dump naar het scherm, want je sloopt de layout niet en het werkt ook bij AJAX en cronjobs, waar je sowieso niks te zien krijgt.

Twee constantes die er soms bij horen

define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

SCRIPT_DEBUG laat WordPress de onverkleinde versies van zijn eigen CSS en JavaScript laden. Zoek je een fout in de editor of in een corescript, dan is dat het verschil tussen leesbare code en één lange regel.

SAVEQUERIES bewaart elke databasequery van de pagina. Nuttig als je zoekt waarom iets traag is, maar het kost geheugen. Zet hem uit zodra je klaar bent.

Query Monitor erbij

Voor het meeste werk is Query Monitor prettiger dan een logbestand. De plugin zet een menu in je adminbalk met alle fouten, queries, hooks en HTTP-verzoeken van de pagina die je op dat moment bekijkt.

Ik gebruik allebei. Query Monitor om te zien wat er op een pagina gebeurt, het log voor alles wat buiten een paginaweergave omgaat. Denk aan cronjobs, webhooks en betalingen die terugkomen van een provider.

En dan weer uitzetten

Dit is de stap die iedereen vergeet. Klaar met zoeken:

define( 'WP_DEBUG', false );

Verwijder daarna het logbestand. Laat je het aan staan, dan groeit dat ding maanden door tot je hostingpakket vol zit. Ik heb sites gezien waar een debug.log van elf gigabyte de hele schijf had opgegeten.

Waar het meestal misgaat

• De defines staan te laag in het bestand. Onder de stop-editing-regel doen ze niets.
• Er staat al ergens een WP_DEBUG. De eerste die PHP tegenkomt wint, de tweede geeft een waarschuwing en wordt genegeerd.
• Geen debug.log te bekennen. Meestal een schrijfrechtenkwestie, of je hebt een pad opgegeven naar een map die niet bestaat.
• Fatale fout maar een leeg log. Sommige fouten liggen vóór WordPress. Kijk dan in het foutlog van je hosting zelf.
• Het log blijft leeg terwijl er duidelijk iets stuk is. Check of je hoster WP_DEBUG overschrijft. Dat gebeurt op sommige managed pakketten.

Tot slot

Debuggen op productie mag, zolang je log niet op het scherm belandt en niet publiek te lezen is. Kan het op een staging-omgeving, doe het daar. Maar sommige fouten laten zich alleen op de echte site zien, en dan is dit de manier om er veilig bij te komen.