Xdebug-module inschakelen en configureren in ServBay

ServBay is een krachtige lokale webontwikkelomgeving die Xdebug standaard integreert voor PHP-ontwikkelaars. Door Xdebug te activeren, kun je de ontwikkelsnelheid van je PHP-toepassingen aanzienlijk verhogen en gemakkelijker code debuggen, prestaties analyseren en code coverage controleren. In dit artikel leggen we stap voor stap uit hoe je Xdebug in ServBay inschakelt en configureert, en hoe je het integreert in populaire IDE’s.

Overzicht van de Xdebug-module

Xdebug is een uitgebreide PHP-extensie, speciaal ontworpen voor debugging en het analyseren van PHP-code. In ServBay is Xdebug standaard aanwezig; je hoeft het dus niet zelf te compileren of te installeren. Dit maakt activeren en instellen bijzonder eenvoudig.

Belangrijkste functies van Xdebug

• Breakpoint-debugging: Zet breakpoints op specifieke regels code. Wanneer het programma hier aankomt, pauzeert de uitvoering zodat je variabelen, call stacks en meer stap voor stap kunt inspecteren.
• Stap-voor-stap debugging: Ondersteunt stapjes (Step Over), het betreden van functies (Step Into) en het verlaten van functies (Step Out), zodat je eenvoudig het verloop van de code kunt volgen.
• Variabelenmonitoring: Bekijk tijdens het debuggen real-time de waarden van lokale en globale variabelen.
• Stacktraces: Geeft bij fouten of exceptions gedetailleerde informatie over de call stack, zodat je snel het probleem kunt lokaliseren.
• Performance profiling: Genereert rapporten over de prestaties van je code, waarmee je knelpunten in de snelheid kunt achterhalen.
• Code coverage-analyse: Meet welk deel van de code door tests wordt geraakt voor een objectieve beoordeling van je testkwaliteit.

In ServBay ingebouwde Xdebug-versies en poorttoewijzing

Voor elke PHP-versie die in ServBay wordt geleverd, is de bijpassende Xdebug-module vooraf geïnstalleerd. Let op: elke PHP-versie gebruikt een eigen Xdebug-luisterpoort verbonden aan het versie-nummer. Dit is belangrijk bij de configuratie van de debugger in je IDE.

PHP-versie	Geïnstalleerde Xdebug-versie	Standaard Xdebug-poort
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Poortregel

De standaardregel voor Xdebug-luisterpoorten is 39000 + het subversienummer van PHP. Bijvoorbeeld, voor PHP 8.3 is de poort 39000 + 83 = 39083, en voor PHP 7.4 is dit 39000 + 74 = 39074. Door deze regel te begrijpen, kun je snel de juiste Xdebug-poort voor elke PHP-versie bepalen.

Xdebug-module activeren

Xdebug activeren in ServBay is zeer eenvoudig; het wordt aanbevolen dit met de grafische gebruikersinterface (GUI) te doen. Je kunt het ook handmatig instellen via een configuratiebestand.

Xdebug activeren via de ServBay GUI

Dit is de snelste en makkelijkste methode:

1. Open de ServBay-applicatie.
2. Selecteer in het linkermenu Talen (Languages).
3. Vouw de sectie PHP uit en kies de PHP-versie waarvoor je Xdebug wil activeren, bijvoorbeeld PHP 8.3.
4. Klik op de knop Extensies naast deze versie.
5. Zoek in de pop-up met extensielijst naar de Xdebug-module.
6. Zet de schakelaar links van de Xdebug-module aan om Xdebug te activeren.
7. Pas indien gewenst de instellingen aan.
8. Klik onderaan het venster op Opslaan.
9. ServBay herstart automatisch het PHP-proces en laadt de module.

Afbeelding: Xdebug inschakelen bij Extensies

Controleren of Xdebug juist is geladen

De meest betrouwbare manier is de PHP-configuratie controleren via de phpinfo() functie.

1. Maak in de rootmap van je ServBay-website (standaard /Applications/ServBay/www) een nieuw PHP-bestand, bijvoorbeeld phpinfo.php.
2. Voeg in phpinfo.php de volgende code toe:

   <?php
   phpinfo();
   ?>

3. Bezoek het bestand in je browser, bijvoorbeeld https://servbay.demo/phpinfo.php (vervang servbay.demo door jouw eigen domeinnaam zoals ingesteld in ServBay).
4. Zoek op de phpinfo-output naar "Xdebug". Zie je een aparte "Xdebug"-sectie met versie-informatie en instellingen, dan is Xdebug correct geladen.

Afbeelding: Xdebug-informatie terugvinden in de phpinfo-output

Xdebug configureren voor debugging in de IDE

Xdebug aanzetten is stap één. Om breakpoints te laten werken, moet je in de IDE (bijvoorbeeld PHPStorm of Visual Studio Code) de juiste PHP-interpreter, debugger en server mappings instellen.

Xdebug instellen in PHPStorm

PHPStorm heeft uitstekende ondersteuning voor Xdebug.

1. Open PHPStorm-instellingen: Start PHPStorm en open de instellingen via File -> Settings (Windows/Linux) of PHPStorm -> Preferences (macOS).

2. PHP CLI-interpreter kiezen:

   • Ga naar Languages & Frameworks -> PHP.
   • In het veld CLI Interpreter, klik op het ...-icoon.
   • Voeg via + de juiste lokale interpreter toe.
   • Selecteer het pad naar de PHP-CLI van ServBay, bijvoorbeeld /Applications/ServBay/package/php/8.3/8.3.7/bin/php (let op: controleer je ServBay-installatiepad).
   • PHPStorm detecteert automatisch versie & extensies, inclusief Xdebug.
   • Klik OK om op te slaan. Afbeelding: Instellen van CLI-interpreter in PHPStorm

3. Xdebug-debug-instellingen aanpassen:

   • Ga naar Languages & Frameworks -> PHP -> Debug.
   • Stel onder Xdebug de Debug Port in die bij de PHP-versie hoort die je gebruikt (bijvoorbeeld 39083 voor PHP 8.3). Deze poort moet overeenkomen met de xdebug.client_port uit je instellingen.
   • Vink Kan externe verbindingen accepteren aan.
   • Klik op Apply en op OK om te bewaren. Afbeelding: Luisterpoort voor Xdebug instellen in PHPStorm

4. Webserver mapping instellen:

   • Navigeer naar Languages & Frameworks -> PHP -> Servers.
   • Voeg via + een nieuwe server toe.
   • Geef een naam (bijvoorbeeld ServBay Localhost).
   • Stel Host in op jouw domeinnaam (servbay.demo).
   • Zet de poort op het gebruikte websitepoortnummer, meestal 443 (HTTPS) of 80 (HTTP).
   • Kies als debugger Xdebug.
   • Vink Gebruik path mappings aan.
   • Stel mapping in: lokale projectmap (Absoluut pad naar lokale bron) naar serverpad (Absoluut pad op de server). Plaats je project bijvoorbeeld op /Applications/ServBay/www/myproject en bezoek je het via https://servbay.demo/, dan map je /Applications/ServBay/www/myproject naar /. Gebruik je een subdomein zoals https://myproject.servbay.demo/ en is de root /Applications/ServBay/www/myproject, mappen beide naar /. Correcte mapping is cruciaal voor goede werking van Xdebug.
   • Klik op OK om op te slaan. Afbeelding: Server en mapping configureren in PHPStorm

5. Debugsessie starten:

   • Open je PHP-project in PHPStorm.
   • Klik links in de codelijn op de breakpoint-lijn (rode cirkel).
   • Start het luisteren voor Xdebug door op het kevertje in de toolbar te klikken. Wordt dit groen, luistert PHPStorm.
   • Bezoek nu je webapplicatie (zoals https://servbay.demo/index.php).
   • Als alles correct is ingesteld, verbindt Xdebug automatisch en pauzeert de code bij je breakpoint. Afbeelding: Xdebug-luisteren starten in PHPStorm

Xdebug instellen in Visual Studio Code (VS Code)

VS Code ondersteunt Xdebug goed via extensies.

1. PHP Debug-extensie installeren:

   • Open VS Code.
   • Ga naar de extensieweerder (Ctrl+Shift+X of Cmd+Shift+X).
   • Zoek "PHP Debug" en installeer de extensie van Felix Becker.

2. launch.json configureren:

   • Open je PHP-projectmap.
   • Ga naar het debug-overzicht (Ctrl+Shift+D of Cmd+Shift+D).
   • Klik op het tandwiel bovenaan en kies "PHP". Dit maakt een launch.json aan in de map .vscode.
   • Bewerk launch.json. Zorg dat de port overeenkomt met de juiste Xdebug-poort (bijvoorbeeld 39083 voor PHP 8.3).
   • Path mappings instellen: Dit is essentieel. Stel pathMappings zo in dat het serverprojectpad gematcht wordt met de juiste lokale map:

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Listen for Xdebug",
                 "type": "php",
                 "request": "launch",
                 "port": 39083, // Pas deze poort aan op basis van jouw PHP-versie
                 "pathMappings": {
                     // Map de root van de ServBay-website naar het lokale pad
                     // Bijvoorbeeld bij /Applications/ServBay/www/myproject
                     // en bezoek via https://servbay.demo/ is '/' gelijk aan de projectroot
                     "/": "${workspaceRoot}"
                     // Bij https://myproject.servbay.demo/ en root /Applications/ServBay/www/myproject
                     // geldt ook: "/" : "${workspaceRoot}"
                 }
             },
             {
                 "name": "Launch currently open script",
                 "type": "php",
                 "request": "launch",
                 "program": "${file}",
                 "cwd": "${fileDirname}",
                 "port": 39083 // Hier ook aanpassen volgens je PHP-versie
             }
         ]
     }

     Pas pathMappings aan volgens de structuur van je project en je ServBay-configuratie. ${workspaceRoot} wijst doorgaans naar de hoofdmap van je geopende project in VS Code.

3. Debuggen starten:

   • Open het PHP-bestand waarin je wilt debuggen.
   • Zet een breakpoint (klik links in de editor).
   • Ga naar het debug-overzicht (Ctrl+Shift+D of Cmd+Shift+D).
   • Selecteer "Listen for Xdebug" in het dropdownmenu.
   • Klik op de groene play knop. De statusbalk van VS Code wordt oranje: er wordt geluisterd naar Xdebug.
   • Bezoek je webapplicatie in de browser. Als het goed is, maakt Xdebug verbinding en pauzeert bij het ingestelde breakpoint.

Veelgestelde vragen (FAQ)

• Q: Xdebug verschijnt niet in phpinfo()?

  • A: Controleer of Xdebug is ingeschakeld via de ServBay GUI of door handmatig xdebug.ini aan te passen.
  • Zorg dat je de juiste PHP-service opnieuw hebt gestart.
  • Controleer het pad naar je xdebug.ini en of de regel zend_extension = xdebug.so niet is uitgecommentarieerd.
  • Kijk in de ServBay-log (/Applications/ServBay/logs/php/<versie>/error.log) voor fouten over het laden van Xdebug.

• Q: De code stopt niet bij breakpoints in de IDE?

  • A: Controleer of je IDE luistert op Xdebug (in PHPStorm is het kevertje groen; in VS Code is de statusbalk oranje).
  • Controleer of de ingestelde Xdebug-poort overeenkomt met zowel de xdebug.client_port in ServBay als de standaardpoort voor je PHP-versie.
  • Check of de padmapping (Path Mapping) in de IDE correct is: server- en lokale paden moeten kloppen. Dit is de meest voorkomende oorzaak van problemen.
  • Controleer je firewall-instellingen: blokkeert deze Xdebug-verbindingen niet? De standaardserie is poort 390xx.
  • Heb je xdebug.start_with_request=trigger gebruikt in xdebug.ini, zorg dan dat je browser of verzoek een trigger bevat (zoals de Xdebug Helper-extensie of ?XDEBUG_TRIGGER=1 in de URL).

• Q: Xdebug verbreekt de verbinding na enige tijd?

  • A: Check de instelling xdebug.remote_autostart of xdebug.start_with_request in xdebug.ini. Als deze op yes staat, start elke request een debugging sessie, wat connectieproblemen kan geven. Gebruik bij voorkeur de trigger-modus.
  • Bekijk de timeout-instellingen van je IDE; soms is daar een te korte debuggingtimeout ingesteld.

Conclusie

Dankzij de ingebouwde en eenvoudig instelbare Xdebug-ondersteuning verlaagt ServBay de drempel voor PHP-ontwikkelaars aanzienlijk om te debuggen. Via de intuïtieve GUI of handmatige configuratie zet je snel Xdebug aan voor elke gewenste PHP-versie. Door samen met krachtige IDE’s als PHPStorm of VS Code te debuggen, kun je efficiënter en nauwkeuriger testen, optimaliseren en waarborgen van codekwaliteit. Het beheersen van Xdebug in ServBay tilt je lokale PHP-ontwikkelworkflow naar een hoger niveau.