Activating XDebug on Visual Studio Code & Laravel Herd

2 min readJun 26, 2024

As I had some trouble today activating XDebug in Visual Studio Code (vscode), I stumbled on this article: https://tommcfarlin.com/how-to-configure-laravel-herd-xdebug-and-visual-studio-code/.

However, it didn’t help me as I ran into some issues. It seems like a good idea to quickly share my setup.

1. Visual Studio Code config

If you don’t have a .vscode/launch.json file yet, open the Command Palette (`Cmd + shift + P`) and type debug. Choose debug: add configuration. The launch.json file will be created/opened for you.

Bottom-right you’ll see a button “Add configuration…”. Click it, choose “Listen for XDebug” and the configuration will be added for you:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9001
        }
    ]
}

Note the port. The default port for XDebug is 9003 but I can already tell you that, in my case, this was part of the issue. It conflicted with php-fpm so I configured it on port 9001.

2. PHP config

Open the php.ini file by clicking Herd icon > Open Configuration Files… A finder window with the path to your php.ini file will be opened. Open it in vscode.

As indeed explained in the Herd Docs (https://herd.laravel.com/docs/1/advanced-usage/xdebug) — be sure to check them out — you should configure the path to use Herd’s XDebug extension.

In my case, this is /Applications/Herd.app/Contents/Resources/xdebug/xdebug-81-x86.so — at least for this project, where I’m using PHP 8.1.

Further more, this is the part of my php.ini settings relevant to using XDebug:

zend_extension=/Applications/Herd.app/Contents/Resources/xdebug/xdebug-81-x86.so
xdebug.mode=debug
xdebug.idekey=vscode
xdebug.client_port=9001
xdebug.start_with_request=yes
xdebug.idekey=vscode

3. Check that php-fpm is running

As there was a conflict in my case, php-fpm couldn’t be loaded. I had to kill it:

ps aux | grep “fpm”
kill <the-id-of-the-process>

4. Restart Laravel Herd

herd restart

Check that FPM is running correctly:

5. Try it out

Set a breakpoint in your file, and start xdebug

Hope this helped! If not, let me know in the comments.

Enjoy your day

Thomas