Freelance Software Developer

Preamble

The ability to be able to debug PHP applications is essential. Recently, when switching to Hyper-V as my Virtual Machine provider, and I found XDebug stopped working.

Researching the issue I found this to be a common problem for Developers using Docker (see https://forums.docker.com/t/solved-how-to-setup-xdebug-and-phpstorm/13641/22).

For context, I should say my set-up is: Windows 10, VSCode, Hyper-V, Vagrant, PHP7.2 and XDebug. If you're using a different set-up, say MacOS or Linux with PHPStorm and PHP7.4, then this is article is still relevant to you, but some of the commands shown will have to be translated.

Port Issues

The problem seemed to be a port connection issue on port 9000. Trying to connect, using the Test-NetConnetion Windows Powershell command, failed.

 Test-NetConnection 10.10.20.1 -Port 9000

XDebug Installation

The xDebug installation wizard, https://xdebug.org/wizard, is a fantastic resource. If you don't how to install xDebug start there. The FAQs are also superb if you hit any unexpected issues.

The only thing I usually do on top of the Wizard's recommendations is to add the following xDebug configuration settings to php.ini file referenced by the webserver.

xdebug.remote_enable=1
xdebug.remote_autostart = 1
xdebug.remote_port="9000"
xdebug.remote_connect_back=1 

Visual Code (Launch.json) Configuration

For PHP debugging from VSCode I highly recommend Felix Beckers PHP XDebug extension for VSCode, see https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-pack.

I won't explain how to install and configure the plugin, see the extension's documentation and https://code.visualstudio.com/docs/editor/debugging#_launch-configurations for more information, but will provide an example Launch.json for reference.

{
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/": "${workspaceRoot}"
            }
        }
    ]
}

The problem Revisited

This configuration works with a VirtualBox set-up. The problem is it doesn't work with Hyper-V (and by extension most Docker set-ups).

Workaround

The workaround is to change the xDebug settings in PHP.ini. Removing the connect back attribute and specifying the IP address of your development machine using xdebug.remote_host . See the example below.

Side note: You can find your IP address using a multitude of different commands on different systems. Try Test-NetConnection(PowerShell), ifconfig(Linux) or ipconfig (Windows Cmd).

[XDebug] 
xdebug.remote_enable=1 
xdebug.remote_autostart = 1 
xdebug.remote_port=9000 
xdebug.remote_host=10.10.20.2

Conclusion

Reconfiguring your XDebug settings in the PHP .ini file, as described above, will get you up and running with XDebug on Hyper-V.

The underlying Port forwarding issue hasn't been resolved, merely sidestepped, here. But that's a problem we can solve another day.

Want to Thank Me?

Did you like the article? Was it helpful? If so why not buy me a coffee using Paypal? Buy me a coffee at https://www.paypal.me/justaguycoding