XDebug Guide

XDebug allows you to debug PHP inside your IDE. Most developers working on PortlandOR is using Visual Studio Code as the IDE. Setup is required in both the Lando environment and the IDE. Running XDebug will slow down your app server. As a result, it's recommended that you only enabled XDebug for debugging sessions.

Prepare Lando environment

1. Create a file xdebug.ini under your app root folder (portlandor). Copy the following lines and save the file:

xdebug.remote_host = 10.0.75.1
xdebug.idekey = vscode-xdebug
xdebug.remote_enable=1
xdebug.remote_port=9000
xdebug.remote_autostart=1

2. In .lando.yml, add two lines to include the xdebug.ini file created in Step 1. Here is the end result.

services:
  appserver:
    xdebug: true
    config:
      conf: xdebug.ini

3. Only rebuild the app server in your Lando environment: lando rebuild -s appserver -y

Prepare Visual Studio Code

1. Install the extension "PHP Debug".
2. Follow menu "Debug -> Open Configurations" to open the launch.json file. In the Listen for XDebug section, add "pathMappings" to map /app/ (the source code folder in Lando app server) to your local APP root folder. "log" is optional. When it's set to true, you can see the debug logs for XDebug in VS Code.

        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "log": true,
            "pathMappings": {
                "/app/": "${workspaceFolder}",
            }
        }

3. Follow menu "Debug -> Start Debugging" or press F5, the XDebug server will start listening for incoming connections.
4. Click at the start of a line in index.php to set a breakpoint.
5. Load any page on your Lando site and verify execution stops at the breakpoint.

In one occasion, the breakpoint was not hit until VS Code is updated to the latest (v1.23.1 at the time of writing). If your breakpoint is not hit, try to update VS Code.