feat: xdebug configurability overhaul by AaronFeledy · Pull Request #247 · lando/php

AaronFeledy · 2026-03-17T02:52:53Z

Summary

Complete overhaul of xdebug support in the PHP plugin, addressing the #1 source of developer pain.

Phase 1: Fix broken stuff

Removed Xdebug 2 settings (remote_autostart) from default php.ini — fixes deprecation warnings on PHP 7.2+ (XDEBUG 3 complains about xdebug.remote_autostart = 1 in /usr/local/etc/php/conf.d/xxx-lando-default.ini #92, Warnings in newer versions of xdebug lando#3389)
Updated xdebugConfig() to use host.lando.internal (Lando core's portable hostname) instead of build-time resolved IP — fixes connection drops on network change (XDebug connection drops when host IP address changes #43) and WSL2 issues (#2540)
Xdebug 2 settings (remote_enable, remote_host) only included for PHP <7.2

Phase 2: Built-in `lando xdebug` toggle

New scripts/xdebug.sh — POSIX /bin/sh compatible toggle script
lando xdebug debug / lando xdebug off / lando xdebug debug,develop — no rebuild required
lando xdebug (no args) shows status: loaded state, mode, client host, client port
Auto-detects apache vs php-fpm for reload
Registered as default tooling (user overrides take precedence)
Addresses Allow faster xdebug on/off toggling lando#1668 (open since 2019, 36+ thumbs up)

Phase 3: Configurable xdebug object

New object format in .lando.yml:

xdebug:
  mode: debug
  start_with_request: yes
  client_host: auto
  client_port: 9003
  log: /tmp/xdebug.log
  idekey: LANDO
  config:
    max_nesting_level: 256

Strict backward compatibility: true, false, and string formats still work identically
Generates dedicated yyy-lando-xdebug.ini (loads after defaults, before user custom)
Runtime toggle (zzz-lando-xdebug.ini) always takes precedence

Phase 4: Developer experience

lando info now includes xdebug configuration (mode, client_host, client_port, start_with_request)

Tests

Comprehensive leia tests covering all phases (backward compat, toggle, config object, pass-through, info output)
Unit tests for normalizeXdebugConfig() and generateXdebugIni() (13 passing)

Related issues

Fixes XDEBUG 3 complains about xdebug.remote_autostart = 1 in /usr/local/etc/php/conf.d/xxx-lando-default.ini #92 (Xdebug 3 deprecation warnings)
Addresses Allow faster xdebug on/off toggling lando#1668 (fast xdebug toggle)
Addresses XDebug / WSL 2: Make xDebug work out-of-the-box. lando#2540 (WSL2 xdebug)
Addresses Warnings in newer versions of xdebug lando#3389 (xdebug warnings)
Addresses XDebug connection drops when host IP address changes #43 (IP change breaks xdebug)

Note

Medium Risk
Moderate risk because it changes how Xdebug is configured/enabled at build/runtime (new ini generation, new defaults, new tooling), which can affect developer debugging behavior across PHP versions.

Overview
Overhauls Xdebug configuration for the PHP service by generating a dedicated yyy-lando-xdebug.ini from .lando.yml (including a new object-style config while keeping boolean/string backward compatibility) and wiring the result into the container via volume mount and XDEBUG_CONFIG.

Adds built-in lando xdebug tooling via a new scripts/xdebug.sh that can toggle xdebug.mode at runtime (writing zzz-lando-xdebug.ini and reloading Apache/PHP-FPM) without requiring lando rebuild, and surfaces key Xdebug settings in lando info output.

Cleans up legacy Xdebug 2 ini settings from the default php.ini, updates examples/docs/tests accordingly, and bumps package-lock.json version metadata.

^{Written by Cursor Bugbot for commit 89a5d67. This will update automatically on new commits. Configure here.}

…recation test

netlify · 2026-03-17T02:52:59Z

✅ Deploy Preview for lando-php ready!

Name	Link
🔨 Latest commit	`89a5d67`
🔍 Latest deploy log	https://app.netlify.com/projects/lando-php/deploys/69ba2fb451b825000866abac
😎 Deploy Preview	https://deploy-preview-247--lando-php.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 81 (🔴 down 8 from production) Accessibility: 98 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

✅ Fixed: XDEBUG_MODE env var silently defeats runtime toggle
- Removed XDEBUG_MODE environment variable from line 315 to allow INI-based toggle script to control xdebug mode without env var override.
✅ Fixed: XDEBUG_CONFIG overrides user-specified client_host setting
- Updated xdebugConfig() function to accept and use the user's normalized configuration values instead of hardcoded values for client_host and log settings.

Or push these changes by commenting:

@cursor push 8dd8b2ff7d

Preview (8dd8b2ff7d)

diff --git a/builders/php.js b/builders/php.js
--- a/builders/php.js
+++ b/builders/php.js
@@ -51,15 +51,15 @@
   version: options.via.split(':')[1],
 });
 
-const xdebugConfig = phpSemver => {
+const xdebugConfig = (phpSemver, normalizedConfig) => {
   const config = [
-    'client_host=host.lando.internal',
+    `client_host=${normalizedConfig.client_host}`,
     'discover_client_host=1',
-    'log=/tmp/xdebug.log',
+    `log=${normalizedConfig.log === false ? '' : normalizedConfig.log}`,
   ];
 
   if (phpSemver && semver.lt(phpSemver, '7.2.0')) {
-    config.push('remote_enable=true', 'remote_host=host.lando.internal');
+    config.push('remote_enable=true', `remote_host=${normalizedConfig.client_host}`);
   }
 
   return config.join(' ');
@@ -311,8 +311,7 @@
         environment: _.merge({}, options.environment, {
           PATH: options.path.join(':'),
           LANDO_WEBROOT: `/app/${options.webroot}`,
-          XDEBUG_CONFIG: xdebugConfig(phpSemver),
-          XDEBUG_MODE: options._xdebugConfig.mode,
+          XDEBUG_CONFIG: xdebugConfig(phpSemver, options._xdebugConfig),
         }),
         networks: (_.startsWith(options.via, 'nginx')) ? {default: {aliases: ['fpm']}} : {default: {}},
         ports: (_.startsWith(options.via, 'apache') && options.version !== 'custom') ? ['80'] : [],

builders/php.js

AaronFeledy · 2026-03-17T03:19:36Z

@cursor push 8dd8b2f

- Remove XDEBUG_MODE env var to allow INI-based toggle to work - Update xdebugConfig() to use user's normalized config values instead of hardcoded values - Fixes client_host and other settings being overridden by XDEBUG_CONFIG env var Applied via @cursor push command

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

✅ Fixed: Hardcoded max_nesting_level duplicates config pass-through entries
- Moved max_nesting_level default (512) to config defaults in normalizeXdebugConfig, eliminating duplicate ini entries.

Or push these changes by commenting:

@cursor push bc1017f136

Preview (bc1017f136)

diff --git a/builders/php.js b/builders/php.js
--- a/builders/php.js
+++ b/builders/php.js
@@ -78,7 +78,9 @@
     client_port: 9003,
     log: '/tmp/xdebug.log',
     idekey: '',
-    config: {},
+    config: {
+      max_nesting_level: 512,
+    },
   };
 
   if (xdebug === true) return _.merge({}, defaults, {mode: 'debug'});
@@ -104,7 +106,6 @@
   const ini = [
     '; Generated by Lando PHP plugin',
     `xdebug.mode = ${config.mode}`,
-    `xdebug.max_nesting_level = 512`,
     `xdebug.start_with_request = ${config.start_with_request}`,
     `xdebug.client_host = ${config.client_host}`,
     `xdebug.client_port = ${config.client_port}`,

builders/php.js

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

✅ Fixed: Test expects XDEBUG_MODE env var that code no longer sets
- Updated the test to check xdebug mode via php -i | grep "xdebug.mode" instead of checking the XDEBUG_MODE environment variable that is no longer set.

Or push these changes by commenting:

@cursor push e62e7d0f9c

Preview (e62e7d0f9c)

diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -52,7 +52,7 @@
 lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set mode from string (backward compat)
-lando exec xdebug-string -- env | grep XDEBUG_MODE | grep "debug,develop"
+lando exec xdebug-string -- php -i | grep "xdebug.mode" | grep "debug,develop"
 
 # Should set mode from object config
 lando exec xdebug-object -- php -i | grep "xdebug.mode" | grep debug

examples/xdebug/README.md

AaronFeledy · 2026-03-17T04:34:32Z

@cursor push e62e7d0

Applied via @cursor push command

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

✅ Fixed: Disabled xdebug changes from falsy to truthy value
- Changed line 287 to preserve false (falsy) when xdebug mode is 'off' instead of setting it to the string 'off' (truthy), maintaining backward compatibility for truthiness checks.

Or push these changes by commenting:

@cursor push f7e206bb7a

Preview (f7e206bb7a)

diff --git a/builders/php.js b/builders/php.js
--- a/builders/php.js
+++ b/builders/php.js
@@ -284,7 +284,7 @@
       }
 
       options._xdebugConfig = normalizeXdebugConfig(options.xdebug);
-      options.xdebug = options._xdebugConfig.mode;
+      options.xdebug = options._xdebugConfig.mode !== 'off' ? options._xdebugConfig.mode : false;
       if (options._xdebugConfig.mode !== 'off') {
         const xdebugFile = path.join(options.confDest, options.defaultFiles.xdebug);
         fs.mkdirSync(options.confDest, {recursive: true});

builders/php.js

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

Bugbot Autofix prepared a fix for the issue found in the latest run.

✅ Fixed: Custom xdebug settings lost when toggling from off
- The yyy-lando-xdebug.ini file is now always generated with all custom settings regardless of mode, ensuring configuration persists when toggling xdebug on.

Or push these changes by commenting:

@cursor push bdb96bca48

Preview (bdb96bca48)

diff --git a/builders/php.js b/builders/php.js
--- a/builders/php.js
+++ b/builders/php.js
@@ -285,12 +285,10 @@
 
       options._xdebugConfig = normalizeXdebugConfig(options.xdebug);
       options.xdebug = options._xdebugConfig.mode;
-      if (options._xdebugConfig.mode !== 'off') {
-        const xdebugFile = path.join(options.confDest, options.defaultFiles.xdebug);
-        fs.mkdirSync(options.confDest, {recursive: true});
-        fs.writeFileSync(xdebugFile, generateXdebugIni(options._xdebugConfig));
-        options.volumes.push(`${xdebugFile}:${options.remoteFiles.xdebug}`);
-      }
+      const xdebugFile = path.join(options.confDest, options.defaultFiles.xdebug);
+      fs.mkdirSync(options.confDest, {recursive: true});
+      fs.writeFileSync(xdebugFile, generateXdebugIni(options._xdebugConfig));
+      options.volumes.push(`${xdebugFile}:${options.remoteFiles.xdebug}`);
 
       options._app.config.tooling = options._app.config.tooling || {};
       if (_.get(options, '_app.config.tooling.xdebug') === undefined) {

builders/php.js

AaronFeledy · 2026-03-18T04:11:45Z

@cursor push bdb96bc

When xdebug mode defaults to 'off', custom settings like client_port, start_with_request, and idekey were not being persisted to the ini file. This caused settings to be lost when toggling xdebug on later. Now the yyy-lando-xdebug.ini file is always created with all settings, regardless of mode, ensuring custom configuration persists through xdebug toggles. Applied via @cursor push command

- Fix config pass-through producing duplicate ini directives by using an ordered Map instead of array appending. Pass-through values now override defaults naturally without duplicates. - Add try/catch around sync fs writes for xdebug ini file to surface meaningful error messages on failure. - Add comments explaining the yyy/zzz ini layering strategy in both builders/php.js and scripts/xdebug.sh.

AaronFeledy added 11 commits March 16, 2026 21:30

fix: remove xdebug2 defaults from php.ini

76cc276

fix: use host.lando.internal for xdebug

87c2d32

Add xdebug toggle helper script

d91c37e

Add xdebug status output

bf5f9c9

Register default xdebug tooling

37e5a8e

feat: normalize xdebug config

d4b80b8

feat: generate dedicated xdebug ini

c23e947

fix: restore max_nesting_level default in generated xdebug ini

6e348d0

Add xdebug config to service info

e4c75ff

Expand xdebug leia coverage

439c5e6

test: add unit tests for xdebug config normalization and fix leia dep…

7d6654e

…recation test

AaronFeledy added 2 commits March 16, 2026 21:55

docs: rewrite xdebug documentation for new features

afd05fd

fix: update Chrome Web Store URL to new domain

4af9cdf

cursor bot reviewed Mar 17, 2026

View reviewed changes

builders/php.js Outdated Show resolved Hide resolved

builders/php.js Show resolved Hide resolved

cursor bot reviewed Mar 17, 2026

View reviewed changes

builders/php.js Outdated Show resolved Hide resolved

fix: CI test failures — xdebug.sh reload logic and leia test assertions

86b5496

cursor bot reviewed Mar 17, 2026

View reviewed changes

examples/xdebug/README.md Outdated Show resolved Hide resolved

cursoragent and others added 2 commits March 17, 2026 04:34

Fix test to check xdebug mode via php -i instead of XDEBUG_MODE env var

e824d06

Applied via @cursor push command

fix: pin swoole version in php-extensions test (6.2.0 compile failure)

7d543ee

cursor bot reviewed Mar 17, 2026

View reviewed changes

builders/php.js Show resolved Hide resolved

AaronFeledy added 2 commits March 17, 2026 18:43

Fix flaky xdebug leia assertions

a650420

Stabilize xdebug config leia checks

aa08622

cursor bot reviewed Mar 18, 2026

View reviewed changes

builders/php.js Show resolved Hide resolved

cursoragent and others added 2 commits March 18, 2026 04:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: xdebug configurability overhaul#247

feat: xdebug configurability overhaul#247
AaronFeledy wants to merge 21 commits intomainfrom
feature/xdebug-configurability

AaronFeledy commented Mar 17, 2026 •

edited by cursor bot

Loading

Uh oh!

netlify bot commented Mar 17, 2026 •

edited

Loading

Uh oh!

cursor bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

AaronFeledy commented Mar 17, 2026

Uh oh!

cursor bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor bot left a comment •

edited

Loading

Uh oh!

Uh oh!

AaronFeledy commented Mar 17, 2026

Uh oh!

cursor bot left a comment •

edited

Loading

Uh oh!

Uh oh!

cursor bot left a comment •

edited

Loading

Uh oh!

Uh oh!

AaronFeledy commented Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

AaronFeledy commented Mar 17, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Phase 1: Fix broken stuff

Phase 2: Built-in lando xdebug toggle

Phase 3: Configurable xdebug object

Phase 4: Developer experience

Tests

Related issues

Uh oh!

netlify bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for lando-php ready!

Uh oh!

cursor bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AaronFeledy commented Mar 17, 2026

Uh oh!

cursor bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AaronFeledy commented Mar 17, 2026

Uh oh!

cursor bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AaronFeledy commented Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AaronFeledy commented Mar 17, 2026 •

edited by cursor bot

Loading

Phase 2: Built-in `lando xdebug` toggle

netlify bot commented Mar 17, 2026 •

edited

Loading

cursor bot left a comment •

edited

Loading

cursor bot left a comment •

edited

Loading

cursor bot left a comment •

edited

Loading

cursor bot left a comment •

edited

Loading

cursor bot left a comment •

edited

Loading