Return to development overview

The ‘Xdebug’ service, which is included in the ‘Local’ package and when active provides debugging information for any client listening on port 9003.

To use this with VSCode you need to install the matching Xdebug client.

Here is a short guide to getting it all working.

  1. Start ‘Local’ and switch on Xdebug for the ‘Local’ site which holds the code you want to debug:

Xdebug is off by default to avoid the processing overhead of running the debugging service. ‘Local’ has already done all the work to correctly configure Xdebug so all you have to do is switch it on for the site.

  1. Start ‘VSCode’ and open the folder containing the code you want to debug, typically the top level plugin folder.
  2. If you have not already done so, install the ‘PHP Debug’ VSCode Extension. The one you want is published by Xdebug.
  3. In VSCode, switch to the ‘Run and Debug’ panel.
  4. If you have not already done so for this folder, click on ‘create a launch.json file’.

If prompted for the language, select ‘PHP’. The editor will open a default ‘launch.json’ file for the project. The default ‘Listen for Xdebug’ settings in the ‘launch.json’ file will be fine for working with a PHP app running under ‘Local’. You can close the launch.json file.

Note: VSCode stores debug settings separately for each folder you work on so you will need to complete step 5 each time you start work on a new code folder. It creates a .vscode folder in the top level folder of the code you are working on. If using source control you should add a .gitignore rule so this file does not get tracked or added to the GitHub repository.

  1. If you have previously completed step 5 for the folder you have open, the ‘Run and Debug’ panel will show the RUN AND DEBUG panel.
    Make sure the configuration chosen is ‘Listen for Xdebug’ then click the ‘run’ button.

The debug panel will appear at the top of the VS Code window:

  1. Add breakpoints. In debug mode, when you hover over a line number in the code editor you get the option to set a break point. Click to add a break point. (Click again to remove.)
  2. Launch WP Admin from ‘Local’ and navigate to whatever you are debugging in the web browser. When the code reaches a break point the PHP code interpreter will halt and Xdebug will send VSCode the information to fill the debug panel. For example:

You can inspect and modify any of the variables available at that point in the execution of the program. You can use the debug panel to step through the program or run to the next break point.

  1. To stop the debugging session, click the Stop button on the small debug panel.