PHP met Xdebug en VSCode onder Fedora

Inleiding

Dezer dagen was het weer eens tijd om één van mijn computers te voorzien van een blanco installatie met Fedora GNU/Linux. Uit ervaring weet ik dat het daadwerkelijke installeren niet meer dan een half uur in beslag neemt. Maar het inrichten en naar wens aanpassen van alle hoeken en gaten van zo'n systeem; daar gaan dagen, soms zelfs weken overheen.

Zo kwam ik vandaag een stukje tegen dat ik nog niet naar behoren had ingericht: het stap-voor-stap debuggen van PHP-code in mijn favoriete ontikkelomgeving Visual Studio Code.

Onderdelen

Een van de bekendste PHP debug-hulpmiddelen is Xdebug. Deze module in PHP geeft je behoorlijk veel mogelijkheden om PHP-code te profileren, optimaliseren en dus ook stap-voor-stap te inspecteren terwijl ze wordt uitgevoerd. Een onmisbaar gereedschap voor een webontwikkelaar.

De installatie van Xdebug is dankzij de installatiewizard heel gebruiksvriendelijk en voor alle gangbare platformen beschikbaar. In mijn geval van Fedora 39 met PHP 8.3 waren het de volgende stappen:

# Install xdebug
sudo dnf install php-pecl-xdebug3

# Add xdebug-settings to PHP's ini directives
sudo tee -a /etc/php.d/99-fwiep.ini << EOF

[Xdebug]
xdebug.mode = develop,debug,profile
xdebug.start_with_request = trigger
EOF

# Restart Apache and PHP to load added module
sudo systemctl restart php-fpm.service
sudo systemctl restart httpd.service

Hierna kun je met behulp van phpinfo() controleren of de module correct geladen en actief is. Eenmaal in de browser kun je gebruik maken van xdebug-helper (Firefox, Chrome), een browser-extensie die het debuggen heel comfortabel in- en uitschakelt. Ook kun je er gemakkelijk mee kiezen tussen stap-voor-stap debuggen, profileren en traceren.

3...2...1...Launch!

In VSCode is de installatie van een extensie vereist: xdebug.php-debug. Daarnaast moet in elk project een zogenaamde launch-configuratie worden toegevoegd. Hierin wordt onder andere de TCP-poort ingesteld waarop Xdebug luistert, en ook een directe link gelegd tussen de bestanden en de werkmap (sleutel pathMappings).

{
    "configurations": [
    {
        "name": "Listen for Xdebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "ignore": [
            "**/vendor/**/*.php"
        ],
        "pathMappings": {
            "/path/to/project-folder": "${workspaceFolder}"
        }
    }
    ]
} 

Na het starten van de debugger met F5, het zetten van een breakpoint in de kantlijn van mijn code en het oproepen van de pagina in mijn browser gebeurde er… niets. Ik was vergeten om met de browser-extensie het debuggen in te schakelen. Klik, verversen en… weer niets.

Debuggen van het debuggen

Zo'n beetje alle documentatie en tutorials op internet waar Xdebug en VSCode worden beschreven stopten op dit punt; het zou zo moeten werken. Xdebug geladen en actief? Ja. Xdebug-extensie geïnstalleerd in VSCode en een launch-configuratie toegevoegd? Ja.

Nee dus. Uiteindelijk kwam ik een met phpinfo() vergelijkbare functie genaamd xdebug_info() op het spoor. De output van deze functie geeft alle mogelijke informatie van Xdebug; veel meer dan in de uitvoer van phpinfo(). Hier zag ik de volgende foutmelding:

"[Step Debug] Creating socket for 'localhost:9003', connect: Permission denied."

Permission denied, toegang geweigerd? Dat klinkt als een probleem met SELinux! Onderzoek met behulp van jounalctl bracht me bij de volgende melding in de logs:

AVC avc:  denied  { name_connect } for  pid=29691
  comm="php-fpm"  dest=9003
  scontext=system_u:system_r:httpd_t:s0
  tcontext=system_u:object_r:unreserved_port_t:s0
  tclass=tcp_socket permissive=0

Oplossing

Het programma setroubleshoot bracht ten slotte met een aantal suggesties de oplossing:

SELinux is preventing php-fpm from name_connect access on the tcp_socket port 9003.

If you want to allow httpd to can network connect
Then you must tell SELinux about this by enabling the 'httpd_can_network_connect' boolean.

Do
setsebool -P httpd_can_network_connect 1

Wat blijkt? Bij het inrichten van mijn nieuwe systeem was ik vergeten om dit commando uit te voeren; het stond wel degelijk in mijn aantekeningen. Maar die zijn zo chaotisch dat ik het niet heb gezien. Nou kan dat natuurlijk ook aan mijn slechtzienheid liggen, maar toch… :)