How to run Xdebug 3 on Vagrant / Homestead with VSCode (on Big Sur Mac)

Question

Suddenly, with a new installation of Vagrant/Homestead running a freshly installed Big Sur (macOS), my (old) Xdebug configuration for some reason didn't want to work with my VSCode.

I spent a good few hours trying to figure it out, trying many different setups but with no luck. Xdebug didn't want to work.

So how to set it up correctly to make it work?

Answer 1

for Xdebug Version 3.0.3

1. set IDE to use a debugging port - 9003

2. modify the /etc/php/7.x/fpm/conf.d/20-xdebug.ini

zend_extension = xdebug.so
xdebug.remote_port = 9003
xdebug.max_nesting_level = 512
xdebug.mode = debug
xdebug.client_host = 192.168.10.1

If Homestead.yaml contains a different subnet for the IP address, this IP address may be different...

BTW, after editing 20-xdebug.ini, restart you FPM like so

$ sudo service php7.4-fpm restart

and restart your browser and IDE

PS

Tested on NetBeans and Vagrant (Laravel homestead) with php 7.4, host - WIN-10

Answer 2

First of all, make sure about which version of PHP-FPM your site is running (change laravel.test to the name of your configured site). Remember that you can choose the PHP version to use for each site in the Homested.yaml file.

$ cat /etc/nginx/sites-available/laravel.test | grep fastcgi_pass
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;

This will tell you which configuration file to edit in the Homestead virtual machine (NB: change 8.0 to your version of PHP, if different).

$ sudo nano /etc/php/8.0/fpm/conf.d/20-xdebug.ini 

Here, you can remove all lines starting with xdebug.* and instead add these lines:

xdebug.mode=debug
xdebug.client_host=192.168.10.1
xdebug.client_port=9003
xdebug.max_nesting_level = 512

NB: 192.168.10.1 is by default the IP address of the host machine in VirtualBox, it is supposed to be different than your actual IP address in your LAN. Note that max_nesting_level is not necessary, it's a default by Homestead so I left it there.

Now in Visual Studio Code on your host machine you can set your launch.json file to the following:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            // "stopOnEntry": true,
            "pathMappings": {
                "/home/vagrant/laravel.test": "${workspaceFolder}"
            },
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]
}

PS. I keep "stopOnEntry": true commented so that I can simply uncomment it when needed, otherwise I simply use breakpoints in vscode.

Answer 3

The main reason that it didn't work correctly anymore is that suddenly with the newest version of Homestead we have a Xdebug in version 3 which changes many options of Xdebug 2. It mostly simplifies the thing but also breaks previous setups. You can read more about the changes done to configuration variables in Xdebug 3 on their page.

For Xdebug to work on Homestead / Vagrant / macOS (Big Sur) these are the steps needed.

1. You have to find xdebug.ini location which is easily done displaying phpinfo() and checking the path, which in my case is: /etc/php/7.3/fpm/conf.d/20-xdebug.ini

2. Open it and edit: sudo vi /etc/php/7.3/fpm/conf.d/20-xdebug.ini:

My configuration looks like:

zend_extension=xdebug.so
xdebug.client_port = 9003
xdebug.max_nesting_level = 512

xdebug.mode=debug
xdebug.start_upon_error = true
xdebug.idekey = VSCODE

; The MacOS way
xdebug.discover_client_host = false
xdebug.client_host = 10.254.254.254

Things that has changed:

• the port - now it is 9003,
• for debugging setup - many options are now set using this one simple option: xdebug.mode=debug

3. You have to save the file and restart php-fpm by: sudo service php7.3-fpm reload

4. For macOS (on my Windows machine this wasn't needed) you have to:

Ensure you have created an Host address alias on MacOS and 10.254.254.254 is aliased to your localhost.

By doing: sudo ifconfig lo0 alias 10.254.254.254. Which is in more detail also explained here.

5. Install VSCode PHP Debug (vscode-php-debug) extension.

6. Configure VSCode by clicking the debug icon from the left menu and then edit JSON file containing debugger configuration.

Paste this:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "My XDebug on Homestead",
            "type": "php",
            "request": "launch",
            "pathMappings": {
                "/home/vagrant/code/myproject": "${workspaceFolder}"
            },
            "port": 9003
        }
    ]
}

7. Finally install Chrome Xdebug Helper extension and turn on the (green bug) debug mode when you want to do the debugging.

8. One extra thing. If you want to enable/disable Xdebug, lets say for performance reasons there is a very easy and fast way to do this.

enable:

sudo phpenmod xdebug
sudo service php7.3-fpm reload

disable:

sudo phpdismod xdebug
sudo service php7.3-fpm reload

As you can see a lot of different things in different places must be set correctly to make it work. It takes a lot of googling and patience so I thought it would be useful to put it here for you and for my future installations. :)