TL;DR: This is everything that needs to be done to install Xdebug with a Homebrew-based environment and to work with the software within Visual Studio Code.


Though I’ve recently become a fan of using Ray (1, 2) for much of my lightweight debugging, this doesn’t mean I don’t think it’s important to have Xdebug installed and configured in Visual Studio Code.

If you follow the steps I’ve outlined starting in the previous post, it’s relatively easy though it still requires a little bit of manual work to get started.

This is how you can set up Xdebug with a Homebrew-based configuration and Visual Studio Code.

Xdebug in Visual Studio Code

In this post, I’m assuming you’re working with:

These packages aren’t necessarily required (well, PHP is but the version and how its installed may vary 🙂) but I’ll be using them for walking through the rest of this post.

Install Xdebug

First, make sure that PECL is installed by running $ which pecl in your terminal.

PECL is a repository for PHP Extensions, providing a directory of all known extensions and hosting facilities for downloading and development of PHP extensions.

Since it’s part of the binaries installed with PHP via Homebrew, then it should be available. On my machine, it’s located in /opt/homebrew/opt/php@7.4/bin/pecl.

Next, in the terminal, install $ pecl install xdebug. This is going to kick off a process that will install Xdebug and set up the module in PHP. At this point, running $ php -v should show that Xdebug is installed.

After that, make sure that ext-xdebug.ini exists in the proper directory. If not, create it. Do this by issuing the following command:

$ touch /opt/homebrew/etc/php/7.4/conf.d/ext-xdebug.ini

Then open the file with whatever editor is convenient and make sure it includes the following:

[xdebug]
xdebug.idekey=ECLIPSE
xdebug.client_port=9003
xdebug.mode=debug
xdebug.start_with_request=yes

Don’t worry about changing the idekey or anything like that; it’s fine as-is. Next, restart PHP using PHP Monitor (or whatever service you’re using in the terminal). In PHP Monitor, this is under Manage Services and Restart Service: php.

Configure Visual Studio Code

Launch Visual Studio Code and, if the Xdebug extension has not yet been installed, then navigate to the extensions panel, search for PHP Debug and then install and enable the plugin.

It should look something like this:

After that, launch Chrome (yeah, it’s needed for this part), and install the Xdebug Helper browser extension.

In Visual Studio Code:

  1. Launch a project
  2. Click on the text that reads create a launch.json file. This text is below the Run and Debug button (if you’ve not already created one, before).
  3. Make sure you’re editing the file within the .vscode directory in the root of your plugin.

Add the following lines to the configuration file:

{
    // 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",
            "port": 9003,
        }
    ]
}

Save the file, launch Google Chrome, and navigate to a page on which your project is running. In the example below, I have a plugin that’s running on the All Pages view of the website.

When the page loads, click on the Xdebug Helper and then click on Debug. This should turn the icon green to show the extension is active.

Return to Visual Studio Code, click on Run and Debug then, in the top of the panel, choose Listen for Xdebug and click the Play icon. This will bring up the set of controls for stopping, pausing, starting, stepping over, and stepping into code.

Find a line in your code that you know will fire and click next to it in the IDE. This will set a breakpoint. Optionally, select a variable that will be set at some point during execution, highlight it, and choose Add to Watch.

Next, reload the page in Chrome and you should see the breakpoint hit and the value of the variable set under the Watch pane.

Xdebug is now properly installed, configured, and running on your machine.

The Rundown

To summarize everything covered in this post, see the list below:

  • Install Xdebug with PECL
  • Write the ext-xdebug.ini file
  • Restart PHP
  • Install the PHP Debug extension for Visual Studio Code
  • Install the Xdebug Helper for Google Chrome
  • Write the .vscode/launch.json file in the root of your project

From here, starting the Xdebug Helper extension and starting Xdebug within Visual Studio Code will give you everything you need to start debugging your code.