DDEV and Xdebug: Debugging and sorting out problems
Update: For current guidance, including DDEV v1.25’s ddev utility xdebug-diagnose tool and full troubleshooting steps, see Xdebug in DDEV: Understanding, Debugging, and Troubleshooting Step Debugging. This post remains as the recording of our original Xdebug contributor training, plus a hands-on demo of the Xdebug protocol using nc/netcat that isn’t repeated elsewhere.
Here’s a recording of our Xdebug contributor Training walking through DDEV and Xdebug.
First of all, congratulations for making step-debugging a priority. It’s my opinion that step-debugging is one of the very first things to learn in any language or environment that we undertake.
Second, please contribute to the Xdebug project. Derick Rethans created this incredible resource and has been maintaining it for 22 years and counting. Making open-source projects sustainable is an obligation for all of us!
DDEV’s Xdebug documentation covers basic usage and setup for PhpStorm, VS Code, and other IDEs. In short: ddev xdebug on, make your IDE listen for Xdebug, then visit a page in your browser. If you have trouble, the updated guide and its ddev utility xdebug-diagnose tool cover troubleshooting in depth, including WSL2.
Here’s a demo that isn’t repeated elsewhere: watching the Xdebug protocol itself with nc/netcat, which makes it obvious that Xdebug is just a network connection from PHP to your IDE over host.docker.internal:9003.
Demonstrating Xdebug’s behavior
You can easily test this out using the handy network utility nc or netcat.
On your host workstation (the same place your IDE is running) you can
nc -l 0.0.0.0 9003(note that different versions of netcat/nc may take slightly different arguments.)
If you then visit your project, for example with ddev exec curl localhost or curl https://<project>.ddev.site you’ll see something like this pop up in the nc session:
<?xml version="1.0" encoding="iso-8859-1"?>
<init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/web/index.php" language="PHP" xdebug:language_version="8.2.19" protocol_version="1.0" appid="5089"><engine version="3.2.2"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2023 by Derick Rethans]]></copyright></init>That’s exactly what your IDE receives from PHP in the same situation. If it doesn’t show up, that’s the same connectivity problem your IDE would have — see the troubleshooting guide for how to resolve it.
Contributions welcome!
We always love to hear your experiences with DDEV, so please do a PR to this blog adding your experience. Info and a training session on how to do a PR to anything in ddev.com is at DDEV Website For Contributors. And if you can improve the DDEV docs, click the pencil at the top of any docs page to add your suggestion.
Past trainings are recorded at contributor training.