Using XDebug in VSCode

Using XDebug in Visual Studio Code is not difficult, but it's easy to miss one detail that prevents the whole thing from working. Here's a step-by-step tutorial:

• Install the "PHP Debug" VSCode extension by Felix Becker

• Go to the debug sidebar by clicking on the icon that looks like this:

• Click on the gear icon to edit the launch.json configuration file

• Make sure that in the "Debug PHP" section, the port is set to "9000"

• Add this section within "Debug PHP":

"pathMappings": {
    "/var/www/vhosts/elentra-1x-me": "${workspaceRoot}",
    "/var/www/vhosts/elentra-1x-api": "${workspaceRoot}/www-root/core/library/vendor/elentrapackages/elentra-1x-api"
}

Note: If you include both repositories in the same workspace, the pathMappings section would instead be:

"pathMappings": {
    "/var/www/vhosts/elentra-1x-me": "${workspaceFolder:elentra-1x-me}",
    "/var/www/vhosts/elentra-1x-api": "${workspaceFolder:elentra-1x-api}"
}

• You can also tell the debugger not to show errors from any code that is in the vendor folder (i.e. third-party code) by defining an ignore section, also within "Debug PHP":

"ignore": [
    "**/vendor/**/*.php"
],

• You can change the name of the section from "Debug PHP" to "Debug Elentra ME", which may help if you switch projects

• Save this file

• Open a terminal window in your "elentra-developer" Docker container

• Look at the /etc/php.d/15-xdebug.inifile and check that the xdebug.remote_enable option is set to "true"

That is all the setup you need, so go to VSCode and click the green "run" triangle at the top of the debug sidebar (beside "Debug PHP" or "Debug Elentra ME" if you changed the section name).

The bottom of the VSCode editor should turn orange and a small debug toolbar should appear near the top of the window. On any executable line of PHP code, click to the left of the line numbers and a small red dot should appear. This is a breakpoint, where PHP will stop before executing the line.

I use the XDebug helper extension in Firefox, so I click on the bug icon in my address bar and select "Debug"

Options for the Firefox XDebug helper

Refresh the page, or click on a link, or do anything else that should execute the code where you placed the breakpoint. The VSCode window should bring itself to the front, with your breakpoint line highlighted. Now you can explore the variables in scope, set watches, and navigate through the call stack. Happy debugging!

Sample launch.json 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": "Debug Elentra ME",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/vhosts/elentra-1x-me": "${workspaceRoot}",           
                "/var/www/vhosts/elentra-1x-api": "${workspaceRoot}/www-root/core/library/vendor/elentrapackages/elentra-1x-api"
            },
            "ignore": [
                "**/vendor/**/*.php"
            ]
        }
    ]
}