MediaWiki-Docker/Configuration recipes/Xdebug config for VS Code

From mediawiki.org

Xdebug for VS Code[edit]

To debug PHP code in VS Code, do the following:

  1. Set up xdebug in the container.
  2. In VS Code, install the PHP Debug extension
  3. Open the MediaWiki codebase in VS Code. Go to the Run tab (play button with a little bug), click "create a launch.json file" and select PHP as the environment. (If you already have a launch.json file, select "add configuration" from the dropdown.) The launch.json file should look something like this:
{
	// 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,
			"pathMappings": {
			  "/var/www/html/w": "${workspaceFolder}"
			}
		},
		{
			"name": "Launch currently open script",
			"type": "php",
			"request": "launch",
			"program": "${file}",
			"cwd": "${fileDirname}",
			"port": 9003
		}
	]
}
  1. The important things are
    1. The pathMappings configuration is defined
    2. The port number corresponds to the the XDEBUG_CONFIG port number in your .env file (9003 by default in XDebug 3.0+; 9000 is the default in older versions).
  2. Set your Xdebug browser extension of choice to listen for the debugger. In the MediaWiki codebase, place a breakpoint in the PHP code you'd like to step through. Visit your local site in the browser and, if the breakpoint is placed on a line of code that's run, the debugger will pause on that line and allow you to step through the code.

Notes:

  1. If the debugger stops on errors or exceptions unexpectedly, in VS Code, uncheck "Everything" in the Breakpoints window within the Run tab.
  2. This won't work for extension codebases opened in VS Code; you must run the debugger from the MediaWiki core codebase (but you can place breakpoints in extension code there).
  3. See MediaWiki-Docker/Configuration recipes/Xdebug#Troubleshooting for more info about troubleshooting your XDebug setup inside MW Docker.