Debugging with Xdebug

Xdebug (opens new window) is an extension for PHP, and provides a range of features to improve the PHP development experience. The setup can depend on your local development environment and which IDE you are using.

Lando, Xdebug and VSCODE

Xdebug can have a signifant performance hit on PHP requests, so by default we usually run local development enviroments without Xdebug enabled.

Here are steps to get debugging in Lando.

1. Enable xdebug with a local Lando file.

The .lando.local.yml can override any of the settings defined in the default .lando.dist.yml that we include with the LocalGov Drupal project.

If you don't already have one, create a .lando.local.yml in the root of your project and make sure it contains the following:

config:
  xdebug: true

2. Rebuild lando

lando rebuild -y

3. In VSCode, enable the PHP Debug extension (opens new window)

4. Click on the Run and Debug icon to set the configuration.

5. Cick 'create a launch.json file'

6. Add the following to the launch.json file

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "log": true,
      "pathMappings": {
        "/app": "${workspaceFolder}/MY_PROJECT",
      }
    }
  ]
}

Note that the path mapping might depend on where you workspace root is. In this example, I have a VSCODE workspace at .~/sites/l.localgov into which I have created the project in the MY_PROJECT folder. Lando runs from within the MY_PROJECT folder, so it maps that folder to /app from within the appserver container.

7. Press the Start Debugging icon to start listening for Xdebug

8. Add a breakpoint to your index.php file by clicking to the left of the line numbers of a line with code on.

9. Load the home page of the site

10. See the script break and provide you with variables and callstack.

DDEV, Xdebug and VSCODE

Xdebug can have a signifant performance hit on PHP requests, so by default we usually run local development enviroments without Xdebug enabled.

1. Enable XDebug with DDEV, assuming a default DDEV Drupal configuration:

ddev xdebug

2. In VSCode, enable the PHP Debug extension (opens new window)

3. Click on the Run and Debug icon to set the configuration.

4. Cick 'create a launch.json file'

5. Add the following to the launch.json file

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "log": true,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}/MY_PROJECT",
      }
    }
  ]
}

Note that the path mapping might depend on where you workspace root is. In this example, I have a workspace into which I have created the project into the MY_PROJECT folder. DDEV runs from within the MY_PROJECT folder, so it maps that folder to /var/www/html

4. Press the Start Debugging icon to start listening for Xdebug

5. Add a breakpoint to your index.php file by clicking to the left of the line numbers of a line with code on.

6. Load the home page of the site

7. See the script break and provide you with variables and callstack.