XDebug connection drops when host IP address changes

[pfrenssen]

This is the same issue as reported in lando/lando#1700. There is now a solution for this.

Currently when the PHP container is built XDebug is configured using the current host IP address in the XDEBUG_CONFIG environment variable (ref.

php/services/php/builder.js

Line 31 in 311eab6

const xdebugConfig = host => ([

).

Example:

XDEBUG_CONFIG: client_host=192.168.1.116 discover_client_host=1 log=/tmp/xdebug.log remote_enable=true remote_host=192.168.1.116

Since the IP address is hardcoded this causes the XDebug connection to be lost when the host address changes (e.g. when switching to a different wifi network).

At the moment the only way to fix it is to run lando rebuild which will update the environment variables.

In the original issue it was mentioned (lando/lando#1700 (comment)) that the best solution would be to use host.docker.internal instead of hardcoding the IP but at the time the issue was created this was not yet supported in Linux. Support for this has been added in Docker version 20.10 (moby/moby#40007).

One potential snag is that on Linux the following host needs to be added to the Docker configuration: host.docker.internal:host-gateway. This is not needed on Windows and OSX.

[pfrenssen]

Here is a proof of concept demonstrating the use of host.docker.internal on Linux. It is a minimal PHP project using the LAMP recipe. With this setup, XDebug works in the browser as well as on the command line (using PHPUnit as an example CLI command). XDebug keeps working successfully when switching networks.

.lando.yml

name: my-lando-app
recipe: lamp
config:
  config:
    php: resources/lando/php.ini
  php: '8.1'
  webroot: .
  xdebug: off

services:
  appserver:
    build:
      - composer install
    scanner: false
    overrides:
      environment:
        XDEBUG_CONFIG:
        XDEBUG_MODE:
        PHP_IDE_CONFIG: "serverName=my-lando-app.lndo.site"
        XDEBUG_SESSION_START: lando
      extra_hosts:
        - "host.docker.internal:host-gateway"

tooling:
  phpunit:
    service: appserver
    description: Runs phpunit with config at /app/phpunit.xml
    cmd: /app/vendor/bin/phpunit -v -c /app/phpunit.xml.dist
  xdebug:
    description: Loads Xdebug in the selected mode. E.g. "lando xdebug develop,debug"
    cmd:
      - appserver: /app/resources/lando/xdebug.sh
    user: root
  xdebug-on:
    description: Turns on Xdebug.
    cmd:
      - appserver: /app/resources/lando/xdebug.sh debug
    user: root
  xdebug-off:
    description: Turns off Xdebug.
    cmd:
      - appserver: /app/resources/lando/xdebug.sh off
    user: root

resources/lando/php.ini

; Always start the debugger when it is enabled using 'lando xdebug-on'.
; Alternatively comment this out and toggle Xdebug using a browser extension. 
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal

; Make profiling output and logs accessible.
xdebug.output_dir=/app/tmp
xdebug.log=/app/tmp/xdebug-log.log

resources/lando/xdebug.sh

#!/bin/bash

if [ "$#" -ne 1 ]; then
  echo xdebug.mode = off > /usr/local/etc/php/conf.d/zzz-lando-xdebug.ini
  /etc/init.d/apache2 reload
  echo "Xdebug has been disabled. To enable: 'lando xdebug <mode>'."
  echo "Valid modes: https://xdebug.org/docs/all_settings#mode."
else
  mode="$1"
  echo xdebug.mode = "$mode" > /usr/local/etc/php/conf.d/zzz-lando-xdebug.ini
  /etc/init.d/apache2 reload
  echo "Xdebug is loaded in "$mode" mode."
fi

index.php

<?php
xdebug_break();
phpinfo();

composer.json

{
    "require-dev": {
        "phpunit/phpunit": "^9.5"
    }
}

PHPStorm server setup

• name: my-lando-app.lndo.site
• host: my-lando-app.lndo.site
• port: 80
• debugger: XDebug
• use path mappings: checked
• map the root project to the absolute path /app on the server

Testing in browser

• Enable XDebug using lando xdebug-on
• Visit https://my-lando-app.lndo.site

Testing in CLI

• Configure PHPStorm to break on the first line in PHP scripts.

$ lando xdebug-on
$ lando phpunit --help

[tcrawf]

I confirm that the above proof of concept worked for me with Docker v24.0.1 and Lando v3.11.0 on Linux (Ubuntu 23.04). I am very happy not to have to rebuild my container every time I switch networks. Thanks Pieter.