XDebug Guide

XDebug allows you to debug PHP inside your IDE. Most developers working on PortlandOR are 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 enable XDebug for debugging sessions.

Prepare Lando environment

Note: This section is included here for completeness, although this should already be included in the code checked out from GitHub.

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

xdebug.mode = debug
xdebug.client_host = ${LANDO_HOST_IP}
xdebug.idekey = vscode-xdebug
xdebug.client_port = 9003
xdebug.start_with_request = trigger
xdebug.max_nesting_level = 256
;xdebug.log = /tmp/xdebug.log

2. .lando.yml needs the following lines to include the xdebug.ini file created in Step 1.

services:
  appserver:
    xdebug: false
    config:
      php: xdebug.ini
    overrides:
      environment:
        XDEBUG_MODE:

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

Prepare Visual Studio Code

1. Install the extension "PHP Debug".
2. Follow menu "Run -> Add Configuration" to open the launch.json file. Change the Listen for XDebug section to the following: ("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": 9003,
            "log": false,
            "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. Or use xdebug_break(); to trigger a breakpoint in the code.
5. Load any page on your Lando site and verify execution stops at the breakpoint.