Debug in Joomla

2. De Debugmodus inschakelen

2.1 Het tabblad Debug-instellingen

Op Systeem → Globale configuratie → Systeem vind je de groep Debug-instellingen met drie velden:

Zet Debug systeem op Ja, klik op Opslaan en herlaad een pagina. De console verschijnt - mits de plugin is ingeschakeld en je hem mag zien (paragraaf 6).

2.2 Foutrapportage hoort bij debuggen

De Debugmodus toont PHP-waarschuwingen, maar PHP genereert die alleen als de foutrapportage het toestaat. Het bijbehorende veld zit een tabblad verderop, op Systeem → Globale configuratie → Server:

Als je een lastig probleem najaagt, zet je Foutrapportage op Maximaal samen met Debug systeem. Je ziet dan elke notice die PHP kan geven. Zet het terug op Systeemstandaard (of Geen) voordat je live gaat, zodat bezoekers nooit een kale PHP-fout zien.

2.3 Wat er gebeurt zodra de Debugmodus aangaat

Het inschakelen van debug verandert meer dan alleen de console. Joomla doet ook het volgende:

• het definieert de constante JDEBUG als true, die het hele CMS controleert (paragraaf 7);
• het start de Profiler van de applicatie, zodat tijdmarkeringen worden vastgelegd;
• het zet GZIP-compressie uit voor het verzoek, zodat de console-HTML niet wordt weggecomprimeerd.

Daarom kan een debugpagina er iets anders uitzien en zich iets anders gedragen dan een normale. De Debugmodus is een diagnostische toestand, geen onzichtbare laag.

4. De Debug-console lezen

Elk tabblad in de console wordt gevuld door een datacollector. Weten wat elk tabblad betekent verandert de balk van ruis in een kaart van het verzoek.

4.1 Het tabblad Queries is waar snelheidsproblemen zich verstoppen

Het tabblad Queries telt elke query en toont de duur. Twee patronen verraden in een oogopslag problemen:

• Een hoog totaalaantal (honderden query's op een pagina) betekent meestal dat een extensie binnen een lus query's uitvoert. Dit is het klassieke "N+1"-probleem.
• Een trage query die boven de rest uitsteekt, wijst op een ontbrekende index of een zware join.

Dezelfde query die vele malen wordt herhaald, wordt ook gemarkeerd, wat snel code blootlegt die de database steeds opnieuw om hetzelfde vraagt in plaats van het te cachen.

Als vuistregel draait een normale Joomla-pagina onder de honderd query's; een paar honderd is een teken om te onderzoeken, en enkele honderden betekent vrijwel altijd dat een extensie in een lus zit. Dit zijn geen harde grenzen - een complexe pagina heeft er terecht meer nodig - maar een plotselinge sprong in het aantal is een betrouwbaar waarschuwingssignaal.

4.2 Het tabblad Profile leest als een tijdlijn

Het tabblad Profile toont benoemde markeringen van het begin van het verzoek tot het eind - "afterInitialise", "afterRoute", "afterDispatch", "afterRender" en meer. De tijd tussen twee markeringen vertelt je welke fase traag is. Een grote sprong voor "afterRender" wijst op het template of de modules; een sprong rond "afterDispatch" wijst op de component die het werk doet.

4.3 Query Traces: ontdek wie een query afvuurde

Weten dat een query traag is, is maar het halve antwoord; je moet ook weten welke extensie hem uitvoerde. Schakel de optie Query Traces in (paragraaf 5.1) en elke query in het tabblad Queries krijgt een call stack - de keten van bestanden en methoden die ertoe leidde, bijvoorbeeld een modulehelper die loadObjectList() aanroept. Dit verandert "120 identieke categorie-query's" in "deze module zit in een lus", omdat de trace het verantwoordelijke bestand en de regel benoemt. Het is de snelste manier om een query toe te wijzen aan de extensie die hem bezit.

6. Bepalen wie de Debugmodus ziet

6.1 De optie Allowed Groups

Standaard, als Debug systeem aan staat, ziet iedereen die de site bezoekt de console - inclusief anonieme bezoekers. Dat is prima op een lokale kopie en gevaarlijk op een openbare. De optie Allowed Groups (filter_groups) beperkt de console tot gekozen gebruikersgroepen.

De plugin controleert het zo:

$filterGroups = (array) $this->params->get('filter_groups', []);

if (!empty($filterGroups)) {
    $userGroups = $user->groups;

    // Toon debug alleen als de gebruiker in een van de toegestane groepen zit
    if (!array_intersect($filterGroups, $userGroups)) {
        return false;   // niet toegestaan - verberg de console
    }
}

Zet Allowed Groups op Super Users (of je ontwikkelaarsgroep) zodat normale bezoekers de console nooit zien, zelfs als debug per ongeluk aan blijft staan.

6.2 Gevoelige waarden worden geredigeerd

De console kan verzoek-, sessie- en configuratiegegevens tonen, waarvan sommige gevoelig zijn. De plugin redigeert automatisch sleutels die op geheimen lijken - wachtwoorden, tokens en dergelijke - voordat ze worden getoond. Het zoekpatroon dekt namen als password, passwd, secret, token en smtppass. Dit verkleint het risico, maar het is geen reden om te ontspannen: een console op een openbare site lekt nog steeds de structuur van query's, bestandspaden en versienummers die een aanvaller helpen.

Behandel de Debug-console als interne informatie. Beperk hem tot een vertrouwde groep en schakel de instelling uit zodra je klaar bent.

6.3 Een echt voorbeeld: het Debug-lek van 2022

Dit is geen theoretisch risico. Ik ben hier in 2022 zelf mee geconfronteerd, nadat een van mijn pas gelanceerde Joomla-sites was gehackt. Tijdens mijn onderzoek heb ik mijn bevindingen en analyse gedeeld met het Joomla Security Strike Team, dat de oorzaak van het probleem heeft achterhaald en de oplossing heeft geïmplementeerd die in Joomla 4.2.4 is uitgebracht.

Vóór Joomla 4.2.4 kon de debug-uitvoer gevoelige verzoekgegevens, waaronder de sessie van een ingelogde gebruiker en CSRF-tokens, blootstellen aan mensen die deze niet mochten zien. Een aanvaller die deze tokens leest, kan de sessie kapen en zich voordoen als die gebruiker. Het Joomla-project heeft dit gedocumenteerd als beveiligingsadvies 20221001 (CVE-2022-27912), "Disclosure of critical information in Debug Mode". Het had betrekking op Joomla 4.0.0 tot en met 4.2.3 en werd verholpen in de beveiligingsrelease Joomla 4.2.4.

De oplossing is precies de hierboven beschreven redactie: het patroon PROTECTED_COLLECTOR_KEYS is in 4.2.4 toegevoegd, zodat wachtwoord- en tokenachtige waarden worden gemaskeerd voordat de console ze weergeeft. Het is een duidelijke herinnering dat de veilige toestand niet “geredigeerde debug op een live site” is, maar “debug uitgeschakeld op een live site”.

Ik heb in het Joomla Community Magazine beschreven hoe een van mijn eigen Joomla 4-sites hierdoor werd getroffen en wat ik hiervan heb geleerd: Hoe mijn nieuwe Joomla 4-website werd gehackt.

8. Je eigen code profilen

8.1 Je eigen tijdmarkeringen toevoegen

Het tabblad Profile is niet beperkt tot core-markeringen. Elke code kan zijn eigen markeringen toevoegen via de Profiler van de applicatie. Elke markering legt de tijd en het geheugen vast sinds het verzoek begon:

use Joomla\CMS\Profiler\Profiler;

$profiler = Profiler::getInstance('Application');

$profiler->mark('mijnExtensie: voor zwaar werk');
$result = $this->doHeavyWork();
$profiler->mark('mijnExtensie: na zwaar werk');

Beide markeringen verschijnen in het tabblad Profile, en het gat ertussen is precies hoelang je zware werk duurde. Dit is de eenvoudigste manier om een vermoedelijk trage methode te meten zonder externe profiler.

8.2 De Server-Timing-header

Als profiling aan staat, schrijft de plugin de markeringen ook in een standaard Server-Timing-responsheader. De ontwikkelaarstools van je browser (het tabblad Netwerk) tonen dan dezelfde tijden bij het verzoek, zodat je ze kunt lezen zonder de console te openen. De rendertijd van modules en de tijd voor toegangscontroles worden opgeteld in eigen vermeldingen, waardoor een traag template makkelijk op te sporen is.

8.3 Gebruik de constante om dure diagnostiek af te schermen

Als je diagnostiek zelf duur is - een grote array dumpen, een trace opbouwen - wikkel het dan in de constante zodat het nooit in productie draait:

if (JDEBUG) {
    Log::add('Payload: ' . print_r($payload, true), Log::DEBUG, 'my-extension');
}

Zo blijft de live site snel terwijl je volledige details krijgt zodra je debug inschakelt.

8.4 Wanneer je Xdebug of een profiler erbij pakt

De Debug-console is een snelle eerste laag: hij vertelt je waar het probleem zit - een trage query, een zware plugin, een trage fase van het verzoek. Om de exacte PHP-regel daarachter te vinden, pak je een step-debugger zoals Xdebug, of een codeprofiler zoals Blackfire of Tideways. De werkwijze is om de Debug van Joomla naar de verdachte component of query te laten wijzen, en daarna het externe hulpmiddel te gebruiken om in te zoomen op de methode die het veroorzaakt. De twee lagen vullen elkaar aan; geen van beide vervangt de ander.

10. Taal debuggen

10.1 Wat Debug taal toont

Zet Debug taal op Ja en Joomla markeert vertaalde tekst op de pagina zodat je de staat van elke tekst kunt zien. Onvertaalde teksten springen eruit, en de console krijgt taaltabbladen die het volgende tonen:

• Taalbestanden - elk .ini-bestand dat Joomla voor deze pagina heeft geladen.
• Taalteksten - de sleutels die zijn gebruikt.
• Taalfouten - sleutels zonder vertaling, of bestanden met syntaxfouten.

Dit is de snelste manier om een ontbrekende vertaling te vinden: de foute sleutel verschijnt op de pagina, en het taaltabblad vertelt je welk bestand hem zou moeten bevatten.

10.2 De markeringstekens

Vertaalde teksten worden op het scherm omgeven door markeringstekens. Een tekst met markeringen aan beide kanten is netjes vertaald; een tekst die als zijn ruwe constantennaam wordt getoond (zoals COM_EXAMPLE_HELLO) heeft helemaal geen vertaling. De optie Debug taalconstanten bepaalt of je voor zulke teksten de constantennaam of de terugvalwaarde ziet.

10.3 Lange voorvoegsels afkappen

Joomla-taalsleutels kunnen lang zijn. De taal-fieldset van de plugin-opties laat je een gemeenschappelijk voor- of achtervoegsel van de getoonde sleutel afkappen, en de optie Strip First Word verwijdert het eerste deel (vaak de naam van de extensie). Deze veranderen alleen hoe sleutels worden getoond in de console; ze raken je vertaalbestanden niet aan.

12. Webservices en de opdrachtregel

12.1 JDEBUG bestaat overal

De constante JDEBUG wordt gedefinieerd in elk ingangspunt - de site, de administrator, de API-applicatie en de CLI. Dezelfde instelling debug raakt ze dus allemaal. Op de opdrachtregel meldt de console van Joomla zelfs de debugstatus in de versieregel:

php cli/joomla.php --version
Joomla! 6.x.x (debug: No)

12.2 Geen Debug-console in JSON-responsen

De Debug-console is HTML, geinjecteerd voor </body>. Een webservices-verzoek geeft JSON terug, dat geen body-tag heeft, dus de plugin injecteert geen console in API-responsen - dat zou de JSON beschadigen. In plaats daarvan stapelt de plugin de gegevens intern op in plaats van ze te tonen wanneer er gegevens voor een niet-HTML-respons worden verzameld. In de praktijk betekent dit dat je de REST-API debugt via logs en de query monitor, niet via een zichtbare balk.

12.3 Geen REST-endpoint voor Debug

Er is geen /api/index.php/v1/-route om debuggen aan of uit te zetten. Debug is een configuratie- en diagnosekwestie, geen gegevens om via een API beschikbaar te stellen. Om het vanuit automatisering te wijzigen, bewerk je de instelling via de backend of, in een gecontroleerde deployment, de waarde debug in configuration.php.

12.4 Geen console bij geplande taken of CLI

De Debug-console bestaat alleen voor een HTML-paginaverzoek. De geplande taken en CLI-commando's van Joomla draaien zonder browserrespons, dus er is geen balk om te lezen - zelfs met debug aan. Als je een taak of een opdrachtregelcommando moet diagnosticeren, val je terug op de hulpmiddelen die geen pagina nodig hebben: schrijf naar het log met Log::add(), voeg Profiler::mark()-aanroepen toe om timing te meten, en zorg dat uitzonderingen worden opgevangen en gelogd. Hetzelfde geldt voor elk achtergrondwerk dat nooit HTML rendert.

14. Veelgemaakte fouten en valkuilen

14.1 Debug staat aan maar er verschijnt niets

Symptoom: Je hebt Debug systeem op Ja gezet maar er verschijnt geen console onderaan de pagina.

Oplossing: Controleer de plugin. De "Systeem - Debug"-plugin moet ingeschakeld zijn onder Systeem → Beheren → Plugins. Controleer ook Allowed Groups - staat daar een groep waar je niet in zit, dan is de console voor jou verborgen.

14.2 De console verschijnt op de live site voor iedereen

Symptoom: Bezoekers melden een vreemde donkere balk met technische gegevens onderaan de pagina.

Oplossing: Debug staat aan in productie met Allowed Groups leeg. Zet Debug systeem uit in de Globale configuratie. Stel als vangnet Allowed Groups in op Super Users zodat dit niet opnieuw kan gebeuren.

14.3 De site is traag nadat je iets "repareerde"

Symptoom: De hele site voelt trager aan dan voorheen, zonder duidelijke oorzaak.

Oplossing: Controleer of debug aan bleef staan. De Debugmodus schakelt GZIP en asset-caching uit en legt elke query vast. Zet debug terug op Nee en de snelheid keert terug.

14.4 Een witte pagina zonder fout

Symptoom: Een pagina is leeg en je kunt niet zien waarom.

Oplossing: Zet Debug systeem aan en stel Foutrapportage in op Maximaal. De verborgen PHP-fout die de lege pagina veroorzaakte, verschijnt nu en wijst naar het bestand en de regel.

14.5 Wachtwoorden zichtbaar in het tabblad Request

Symptoom: Je maakt je zorgen dat de console een inlogwachtwoord toont.

Oplossing: De plugin redigeert sleutels die op geheimen lijken, maar het veiligste antwoord is om de console nooit te draaien waar onvertrouwde mensen hem kunnen zien. Beperk Allowed Groups, en schakel Track Request History nooit in behalve voor een korte, begeleide test.

14.6 Vertalingen ogen prima met debug uit maar kapot met debug aan

Symptoom: Tekst toont vreemde markeringstekens eromheen.

Oplossing: Dat is Debug taal die zijn werk doet - de markeringen zijn hoe het de vertaalstaat toont. Zet Debug taal uit en de markeringen verdwijnen; ze worden nooit aan normale bezoekers getoond.

16. In het kort

SYSTEM DEBUG AANZETTEN  Systeem -> Globale configuratie -> Systeem -> Debug-instellingen -> Debug systeem = Ja
TAAL DEBUG AANZETTEN    zelfde tabblad -> Debug taal = Ja
FOUTRAPPORTAGE          Systeem -> Globale configuratie -> Server -> Foutrapportage = Maximaal
DE PLUGIN               Systeem -> Beheren -> Plugins -> Systeem - Debug
BEPERK WIE HEM ZIET     Systeem - Debug-plugin -> Opties -> Allowed Groups = Super Users

INSTELLINGEN (configuration.php)
  debug             0 uit / 1 aan   (definieert JDEBUG)
  debug_lang        0 uit / 1 aan
  error_reporting   default / none / simple / maximum
  log_deprecated    log verouderde API-aanroepen

CONSOLE-TABBLADEN
  Info Profile Queries Memory Request Session User Log  + taaltabbladen

BELANGRIJKE PLUGIN-OPTIES
  filter_groups          wie de console mag zien (leeg = iedereen)
  queries                toon het tabblad Queries
  query_traces           voeg een call stack toe aan elke query (benoemt de boosdoener)
  query_explains         voer EXPLAIN uit op select-query's
  refresh_assets         breek asset-cache bij elke herlaadbeurt
  log-deprecated-core    splits core- en extensie-deprecations
  track_request_history  sla verzoeken op schijf op (RISICOVOL - uit)

CODE
  Staat debug aan? if (JDEBUG) { ... }
  Tijdmarkering    Profiler::getInstance('Application')->mark('label')
  Afgeschermd log  if (JDEBUG) Log::add($msg, Log::DEBUG, 'my-ext')

CLI
  Toon debugstatus php cli/joomla.php --version   ->  (debug: No)