From 76cc27685a878595a34c36cc7e48721b7224f3b4 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:30:34 -0500
Subject: [PATCH 01/21] fix: remove xdebug2 defaults from php.ini

---
 config/php.ini | 1 -
 1 file changed, 1 deletion(-)

diff --git a/config/php.ini b/config/php.ini
index 8e757000..551e72d4 100644
--- a/config/php.ini
+++ b/config/php.ini
@@ -27,7 +27,6 @@ date.timezone = "UTC"
 
 ; Xdebug
 xdebug.max_nesting_level = 512
-xdebug.remote_autostart = 1
 xdebug.start_with_request = trigger
 xdebug.mode = ${XDEBUG_MODE}
 

From 87c2d326ff28cc9ce1416046a911f40696d623e8 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:31:10 -0500
Subject: [PATCH 02/21] fix: use host.lando.internal for xdebug

---
 builders/php.js | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/builders/php.js b/builders/php.js
index 3d1ebf4b..d6ffa808 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -50,13 +50,19 @@ const nginxConfig = options => ({
   version: options.via.split(':')[1],
 });
 
-const xdebugConfig = host => ([
-  `client_host=${host}`,
-  'discover_client_host=1',
-  'log=/tmp/xdebug.log',
-  'remote_enable=true',
-  `remote_host=${host}`,
-].join(' '));
+const xdebugConfig = phpSemver => {
+  const config = [
+    'client_host=host.lando.internal',
+    'discover_client_host=1',
+    'log=/tmp/xdebug.log',
+  ];
+
+  if (phpSemver && semver.lt(phpSemver, '7.2.0')) {
+    config.push('remote_enable=true', 'remote_host=host.lando.internal');
+  }
+
+  return config.join(' ');
+};
 
 const detectDatabaseClient = (options, debug = () => {}) => {
   if (options.db_client === false) return null;
@@ -231,7 +237,7 @@ module.exports = {
         environment: _.merge({}, options.environment, {
           PATH: options.path.join(':'),
           LANDO_WEBROOT: `/app/${options.webroot}`,
-          XDEBUG_CONFIG: xdebugConfig(options._app.env.LANDO_HOST_IP),
+          XDEBUG_CONFIG: xdebugConfig(phpSemver),
           XDEBUG_MODE: (options.xdebug === false) ? 'off' : options.xdebug,
         }),
         networks: (_.startsWith(options.via, 'nginx')) ? {default: {aliases: ['fpm']}} : {default: {}},

From d91c37ec0d871f4d946841906db3958bc7e3628b Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:34:28 -0500
Subject: [PATCH 03/21] Add xdebug toggle helper script

---
 scripts/xdebug.sh | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100755 scripts/xdebug.sh

diff --git a/scripts/xdebug.sh b/scripts/xdebug.sh
new file mode 100755
index 00000000..06f1d76c
--- /dev/null
+++ b/scripts/xdebug.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+
+set -eu
+
+XDEBUG_INI="/usr/local/etc/php/conf.d/zzz-lando-xdebug.ini"
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+reload_web_server() {
+  kill -USR2 "$(pgrep -o php-fpm)" 2>/dev/null || /etc/init.d/apache2 reload 2>/dev/null || true
+}
+
+print_usage() {
+  printf 'Usage: %s [status|off|debug|debug,develop|profile|trace|<mode>]\n' "$(basename "$0")"
+}
+
+set_mode() {
+  printf 'xdebug.mode = %s\n' "$1" > "$XDEBUG_INI"
+}
+
+MODE="${1:-}"
+
+case "$MODE" in
+  '')
+    print_usage
+    ;;
+  off)
+    set_mode off
+    reload_web_server
+    printf '%bXdebug disabled.%b\n' "$RED" "$NC"
+    ;;
+  status)
+    print_usage
+    ;;
+  *)
+    docker-php-ext-enable xdebug 2>/dev/null || true
+    set_mode "$MODE"
+    reload_web_server
+    printf '%bXdebug enabled in %s mode.%b\n' "$GREEN" "$MODE" "$NC"
+    ;;
+esac

From bf5f9c9c8c330cf5b7ec1ac258ddbe4a7ec3f092 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:34:47 -0500
Subject: [PATCH 04/21] Add xdebug status output

---
 scripts/xdebug.sh | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/scripts/xdebug.sh b/scripts/xdebug.sh
index 06f1d76c..71815136 100755
--- a/scripts/xdebug.sh
+++ b/scripts/xdebug.sh
@@ -16,6 +16,31 @@ print_usage() {
   printf 'Usage: %s [status|off|debug|debug,develop|profile|trace|<mode>]\n' "$(basename "$0")"
 }
 
+get_ini_value() {
+  VALUE=$(php -r "echo ini_get('$1');" 2>/dev/null || true)
+  if [ -n "$VALUE" ]; then
+    printf '%s\n' "$VALUE"
+  else
+    printf '(not set)\n'
+  fi
+}
+
+print_status() {
+  if php -m | grep -qi '^xdebug$'; then
+    LOADED='yes'
+  else
+    LOADED='no'
+  fi
+
+  printf '%bXdebug status%b\n' "$BLUE" "$NC"
+  printf 'Loaded: %s\n' "$LOADED"
+  printf 'Mode: %s\n' "$(get_ini_value 'xdebug.mode')"
+  printf 'Client host: %s\n' "$(get_ini_value 'xdebug.client_host')"
+  printf 'Client port: %s\n' "$(get_ini_value 'xdebug.client_port')"
+  printf 'Start with request: %s\n' "$(get_ini_value 'xdebug.start_with_request')"
+  print_usage
+}
+
 set_mode() {
   printf 'xdebug.mode = %s\n' "$1" > "$XDEBUG_INI"
 }
@@ -24,7 +49,7 @@ MODE="${1:-}"
 
 case "$MODE" in
   '')
-    print_usage
+    print_status
     ;;
   off)
     set_mode off
@@ -32,7 +57,7 @@ case "$MODE" in
     printf '%bXdebug disabled.%b\n' "$RED" "$NC"
     ;;
   status)
-    print_usage
+    print_status
     ;;
   *)
     docker-php-ext-enable xdebug 2>/dev/null || true

From 37e5a8e4f78a5e40a10ac8297f8caf0f54182a21 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:35:13 -0500
Subject: [PATCH 05/21] Register default xdebug tooling

---
 builders/php.js | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/builders/php.js b/builders/php.js
index d6ffa808..c4bfc5d3 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -228,6 +228,16 @@ module.exports = {
       // If xdebug is set to "true" then map it to "debug"
       if (options.xdebug === true) options.xdebug = 'debug';
 
+      options._app.config.tooling = options._app.config.tooling || {};
+      if (_.get(options, '_app.config.tooling.xdebug') === undefined) {
+        options._app.config.tooling.xdebug = {
+          service: options.name,
+          description: 'Toggle Xdebug mode',
+          cmd: '/etc/lando/service/helpers/xdebug.sh',
+          user: 'root',
+        };
+      }
+
       // for older generation models
       if (_.includes(options.gen2, options.version)) options.suffix = '2';
 

From d4b80b89603b32d90aeaca680933585bf3c462b9 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:39:26 -0500
Subject: [PATCH 06/21] feat: normalize xdebug config

---
 builders/php.js | 43 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/builders/php.js b/builders/php.js
index c4bfc5d3..ab69450a 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -64,6 +64,36 @@ const xdebugConfig = phpSemver => {
   return config.join(' ');
 };
 
+/**
+ * Normalizes xdebug configuration into a consistent object shape.
+ * @param {boolean|string|Object} xdebug - The user-provided xdebug configuration.
+ * @return {Object} The normalized xdebug configuration.
+ */
+const normalizeXdebugConfig = xdebug => {
+  const defaults = {
+    mode: 'off',
+    start_with_request: 'trigger',
+    client_host: 'host.lando.internal',
+    client_port: 9003,
+    log: '/tmp/xdebug.log',
+    idekey: '',
+    config: {},
+  };
+
+  if (xdebug === true) return _.merge({}, defaults, {mode: 'debug'});
+  if (xdebug === false || _.isNil(xdebug)) return _.merge({}, defaults, {mode: 'off'});
+  if (_.isString(xdebug)) return _.merge({}, defaults, {mode: xdebug});
+
+  if (_.isPlainObject(xdebug)) {
+    const normalized = _.merge({}, defaults, xdebug);
+    if (normalized.client_host === 'auto') normalized.client_host = 'host.lando.internal';
+    normalized.config = _.isPlainObject(normalized.config) ? normalized.config : {};
+    return normalized;
+  }
+
+  return _.merge({}, defaults, {mode: xdebug});
+};
+
 const detectDatabaseClient = (options, debug = () => {}) => {
   if (options.db_client === false) return null;
   if (options.db_client && options.db_client !== 'auto') return options.db_client;
@@ -156,7 +186,7 @@ const parseConfig = options => {
 };
 
 // Builder
-module.exports = {
+const phpBuilder = {
   name: 'php',
   config: {
     version: '7.4',
@@ -225,8 +255,8 @@ module.exports = {
         options.command.unshift('docker-php-entrypoint');
       }
 
-      // If xdebug is set to "true" then map it to "debug"
-      if (options.xdebug === true) options.xdebug = 'debug';
+      options._xdebugConfig = normalizeXdebugConfig(options.xdebug);
+      options.xdebug = options._xdebugConfig.mode;
 
       options._app.config.tooling = options._app.config.tooling || {};
       if (_.get(options, '_app.config.tooling.xdebug') === undefined) {
@@ -248,7 +278,7 @@ module.exports = {
           PATH: options.path.join(':'),
           LANDO_WEBROOT: `/app/${options.webroot}`,
           XDEBUG_CONFIG: xdebugConfig(phpSemver),
-          XDEBUG_MODE: (options.xdebug === false) ? 'off' : options.xdebug,
+          XDEBUG_MODE: options._xdebugConfig.mode,
         }),
         networks: (_.startsWith(options.via, 'nginx')) ? {default: {aliases: ['fpm']}} : {default: {}},
         ports: (_.startsWith(options.via, 'apache') && options.version !== 'custom') ? ['80'] : [],
@@ -269,7 +299,7 @@ module.exports = {
       addBuildStep(['touch /tmp/xdebug.log && chmod 666 /tmp/xdebug.log'], options._app, options.name, 'build_as_root_internal');
 
       // Add build step to enable xdebug
-      if (options.xdebug) {
+      if (options._xdebugConfig.mode !== 'off') {
         addBuildStep(['docker-php-ext-enable xdebug'], options._app, options.name, 'build_as_root_internal');
       }
 
@@ -325,3 +355,6 @@ module.exports = {
     }
   },
 };
+
+module.exports = phpBuilder;
+module.exports.normalizeXdebugConfig = normalizeXdebugConfig;

From c23e94700dc45324ce18baeaf5ecb17aca3f4ef9 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:40:28 -0500
Subject: [PATCH 07/21] feat: generate dedicated xdebug ini

---
 builders/php.js | 34 ++++++++++++++++++++++++++++++++++
 config/php.ini  |  5 -----
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/builders/php.js b/builders/php.js
index ab69450a..fad3daad 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -1,6 +1,7 @@
 'use strict';
 
 // Modules
+const fs = require('fs');
 const _ = require('lodash');
 const path = require('path');
 const semver = require('semver');
@@ -94,6 +95,30 @@ const normalizeXdebugConfig = xdebug => {
   return _.merge({}, defaults, {mode: xdebug});
 };
 
+/**
+ * Generates xdebug ini contents from normalized xdebug configuration.
+ * @param {Object} config - The normalized xdebug configuration.
+ * @return {string} The generated xdebug ini contents.
+ */
+const generateXdebugIni = config => {
+  const ini = [
+    '; Generated by Lando PHP plugin',
+    `xdebug.mode = ${config.mode}`,
+    `xdebug.start_with_request = ${config.start_with_request}`,
+    `xdebug.client_host = ${config.client_host}`,
+    `xdebug.client_port = ${config.client_port}`,
+  ];
+
+  if (config.log !== false) ini.push(`xdebug.log = ${config.log}`);
+  if (!_.isEmpty(config.idekey)) ini.push(`xdebug.idekey = ${config.idekey}`);
+
+  _.forEach(config.config, (value, key) => {
+    ini.push(`xdebug.${key} = ${value}`);
+  });
+
+  return `${ini.join('\n')}\n`;
+};
+
 const detectDatabaseClient = (options, debug = () => {}) => {
   if (options.db_client === false) return null;
   if (options.db_client && options.db_client !== 'auto') return options.db_client;
@@ -211,6 +236,7 @@ const phpBuilder = {
     phpServer: 'apache',
     defaultFiles: {
       _php: 'php.ini',
+      xdebug: 'yyy-lando-xdebug.ini',
       vhosts: 'default.conf',
       // server: @TODO? DO THE PEOPLE DEMAND IT?
     },
@@ -221,6 +247,7 @@ const phpBuilder = {
     },
     remoteFiles: {
       _php: '/usr/local/etc/php/conf.d/xxx-lando-default.ini',
+      xdebug: '/usr/local/etc/php/conf.d/yyy-lando-xdebug.ini',
       vhosts: '/etc/apache2/sites-enabled/000-default.conf',
       php: '/usr/local/etc/php/conf.d/zzz-lando-my-custom.ini',
       pool: '/usr/local/etc/php-fpm.d/zz-lando.conf',
@@ -257,6 +284,12 @@ const phpBuilder = {
 
       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}`);
+      }
 
       options._app.config.tooling = options._app.config.tooling || {};
       if (_.get(options, '_app.config.tooling.xdebug') === undefined) {
@@ -358,3 +391,4 @@ const phpBuilder = {
 
 module.exports = phpBuilder;
 module.exports.normalizeXdebugConfig = normalizeXdebugConfig;
+module.exports.generateXdebugIni = generateXdebugIni;
diff --git a/config/php.ini b/config/php.ini
index 551e72d4..0670f71c 100644
--- a/config/php.ini
+++ b/config/php.ini
@@ -25,11 +25,6 @@ date.timezone = "UTC"
 ;; PACKAGE SETTINGS ;;
 ;;;;;;;;;;;;;;;;;;;;;;
 
-; Xdebug
-xdebug.max_nesting_level = 512
-xdebug.start_with_request = trigger
-xdebug.mode = ${XDEBUG_MODE}
-
 ; Globals
 expose_php = on
 max_execution_time = 90

From 6e348d0718f7917f8f0930db4b78170585a5aa6a Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:46:15 -0500
Subject: [PATCH 08/21] fix: restore max_nesting_level default in generated
 xdebug ini

---
 .gitignore        | 1 +
 builders/php.js   | 1 +
 package-lock.json | 2 +-
 3 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 8b56b4be..c1b8768b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,4 @@ config.*.timestamp-*-*.*
 
 # YARN
 yarn.lock
+.agents/ralph
diff --git a/builders/php.js b/builders/php.js
index fad3daad..196055af 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -104,6 +104,7 @@ const generateXdebugIni = config => {
   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}`,
diff --git a/package-lock.json b/package-lock.json
index 2ee1211b..c4257f79 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6,7 +6,7 @@
   "packages": {
     "": {
       "name": "@lando/php",
-      "version": "1.11.2",
+      "version": "1.12.0",
       "license": "MIT",
       "dependencies": {
         "@lando/nginx": "^1.5.0",

From e4c75fff36ea55c19307807c44d71112c45e184c Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:47:53 -0500
Subject: [PATCH 09/21] Add xdebug config to service info

---
 builders/php.js | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/builders/php.js b/builders/php.js
index 196055af..cd1b4d03 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -319,7 +319,15 @@ const phpBuilder = {
         volumes: options.volumes,
         command: options.command.join(' '),
       };
-      options.info = {via: options.via};
+      options.info = {
+        via: options.via,
+        xdebug: {
+          mode: options._xdebugConfig.mode,
+          client_host: options._xdebugConfig.client_host,
+          client_port: options._xdebugConfig.client_port,
+          start_with_request: options._xdebugConfig.start_with_request,
+        },
+      };
 
       // Determine the appropriate composer version to install if not specified
       if (options.composer_version === true || options.composer_version === '') {

From 439c5e63815b7f1af5b30076108ddfd52534f069 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:48:39 -0500
Subject: [PATCH 10/21] Expand xdebug leia coverage

---
 examples/xdebug/.lando.yml | 45 ++++++++++++++++++----------
 examples/xdebug/README.md  | 60 +++++++++++++++++++++++++++++++-------
 2 files changed, 78 insertions(+), 27 deletions(-)

diff --git a/examples/xdebug/.lando.yml b/examples/xdebug/.lando.yml
index 57dd20c1..34dd2e98 100644
--- a/examples/xdebug/.lando.yml
+++ b/examples/xdebug/.lando.yml
@@ -1,23 +1,36 @@
-name: lando-phpxdebug
+name: lando-php-xdebug
 services:
-  xdebug2:
-    type: php:5.6
+  # Backward compat: boolean true
+  xdebug-true:
+    type: php:8.4
     xdebug: true
-  xdebug3on:
-    type: php
-    xdebug: true
-  xdebug3off:
-    type: php
+  # Backward compat: boolean false
+  xdebug-false:
+    type: php:8.4
     xdebug: false
-  xdebug3:
-    type: php
+  # Backward compat: string mode
+  xdebug-string:
+    type: php:8.4
     xdebug: "debug,develop"
-  manual:
-    type: php
-    xdebug: true
-    build_as_root:
-      - pecl uninstall xdebug
-      - pecl install xdebug-3.0.4
+  # New object format
+  xdebug-object:
+    type: php:8.4
+    xdebug:
+      mode: debug
+      start_with_request: "yes"
+      client_port: 9003
+  # Object with config pass-through
+  xdebug-passthrough:
+    type: php:8.4
+    xdebug:
+      mode: debug
+      config:
+        max_nesting_level: 256
+  # Object format disabled
+  xdebug-off-object:
+    type: php:8.4
+    xdebug:
+      mode: "off"
 
 # This is important because it lets lando know to test against the plugin in this repo
 # DO NOT REMOVE THIS!
diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
index 69b05625..cb9e37ec 100644
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -3,7 +3,7 @@
 This example exists primarily to test the following documentation:
 
 * [PHP Service](https://docs.lando.dev/config/php.html)
-* [Using XDebug](https://docs.lando.dev/config/php.html#using-xdebug)
+* [Using Xdebug](https://docs.lando.dev/config/php.html#using-xdebug)
 
 And probably other stuff
 
@@ -22,20 +22,58 @@ lando start
 Run the following commands to validate things are rolling as they should.
 
 ```bash
-# Should enable xdebug 2 for php 5.6
-lando exec xdebug2 -- php --re xdebug | head -1 | grep "xdebug version 2."
+# Should not have xdebug 2 deprecation warnings
+lando exec xdebug-true -- php -v 2>&1 | grep -v "has been renamed" | grep -v "remote_autostart"
 
-# Should enable xdebug 3 for php 7.2+
-lando exec xdebug3on -- php --re xdebug | head -1 | grep "xdebug version 3."
+# Should use host.lando.internal in XDEBUG_CONFIG
+lando exec xdebug-true -- env | grep XDEBUG_CONFIG | grep host.lando.internal
 
-# Should not enable xdebug by when set to false
-lando exec xdebug3off -- php -m | grep xdebug || echo $? | grep 1
+# Should have world-writable xdebug log
+lando exec xdebug-true -- stat -c "%a" /tmp/xdebug.log | grep 666
 
-# Should use develop, debug if defined
-lando exec xdebug3 -- env | grep 'XDEBUG_MODE' | grep 'debug,develop'
+# Should not load xdebug when disabled
+lando exec xdebug-false -- php -m | grep xdebug || echo $? | grep 1
 
-# Should use xdebug version 3.0.4 if installed
-lando exec manual -- php --re xdebug | head -1 | grep "xdebug version 3.0.4"
+# Should have xdebug script available
+lando exec xdebug-true -- test -f /etc/lando/service/helpers/xdebug.sh
+
+# Should be able to toggle xdebug off at runtime
+lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh off
+lando exec xdebug-true -- php -r "echo ini_get('xdebug.mode');" | grep off
+
+# Should be able to toggle xdebug back on
+lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh debug
+lando exec xdebug-true -- php -r "echo ini_get('xdebug.mode');" | grep debug
+
+# Should show status with no arguments
+lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh | grep -i "mode"
+
+# Should enable xdebug when set to true (backward compat)
+lando exec xdebug-true -- php -r "echo ini_get('xdebug.mode');" | grep debug
+
+# Should set mode from string (backward compat)
+lando exec xdebug-string -- php -r "echo ini_get('xdebug.mode');" | grep "debug,develop"
+
+# Should set mode from object config
+lando exec xdebug-object -- php -r "echo ini_get('xdebug.mode');" | grep debug
+
+# Should set start_with_request from object config
+lando exec xdebug-object -- php -r "echo ini_get('xdebug.start_with_request');" | grep yes
+
+# Should apply config pass-through settings
+lando exec xdebug-passthrough -- php -r "echo ini_get('xdebug.max_nesting_level');" | grep 256
+
+# Should not load xdebug when object mode is off
+lando exec xdebug-off-object -- php -m | grep xdebug || echo $? | grep 1
+
+# Should have generated xdebug ini file
+lando exec xdebug-true -- test -f /usr/local/etc/php/conf.d/yyy-lando-xdebug.ini
+
+# Should show xdebug info in lando info
+lando info -s xdebug-true --deep | grep xdebug
+
+# Should show mode in info output
+lando info -s xdebug-true --deep | grep debug
 ```
 
 ## Destroy tests

From 7d6654e396c662710d70b99043059ec67107d6b1 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:52:05 -0500
Subject: [PATCH 11/21] test: add unit tests for xdebug config normalization
 and fix leia deprecation test

---
 examples/xdebug/README.md  |   2 +-
 test/xdebug-config.spec.js | 118 +++++++++++++++++++++++++++++++++++++
 2 files changed, 119 insertions(+), 1 deletion(-)
 create mode 100644 test/xdebug-config.spec.js

diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
index cb9e37ec..0aff2f33 100644
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -23,7 +23,7 @@ Run the following commands to validate things are rolling as they should.
 
 ```bash
 # Should not have xdebug 2 deprecation warnings
-lando exec xdebug-true -- php -v 2>&1 | grep -v "has been renamed" | grep -v "remote_autostart"
+lando exec xdebug-true -- php -v 2>&1 | grep -c "has been renamed\|remote_autostart" | grep 0
 
 # Should use host.lando.internal in XDEBUG_CONFIG
 lando exec xdebug-true -- env | grep XDEBUG_CONFIG | grep host.lando.internal
diff --git a/test/xdebug-config.spec.js b/test/xdebug-config.spec.js
new file mode 100644
index 00000000..7de4bbea
--- /dev/null
+++ b/test/xdebug-config.spec.js
@@ -0,0 +1,118 @@
+'use strict';
+
+const chai = require('chai');
+const expect = chai.expect;
+
+const {normalizeXdebugConfig, generateXdebugIni} = require('../builders/php');
+
+describe('normalizeXdebugConfig', () => {
+  it('should normalize true to mode debug', () => {
+    const result = normalizeXdebugConfig(true);
+    expect(result.mode).to.equal('debug');
+    expect(result.client_host).to.equal('host.lando.internal');
+    expect(result.client_port).to.equal(9003);
+  });
+
+  it('should normalize false to mode off', () => {
+    const result = normalizeXdebugConfig(false);
+    expect(result.mode).to.equal('off');
+  });
+
+  it('should normalize undefined to mode off', () => {
+    const result = normalizeXdebugConfig(undefined);
+    expect(result.mode).to.equal('off');
+  });
+
+  it('should normalize null to mode off', () => {
+    const result = normalizeXdebugConfig(null);
+    expect(result.mode).to.equal('off');
+  });
+
+  it('should normalize a string to its mode', () => {
+    const result = normalizeXdebugConfig('debug,develop');
+    expect(result.mode).to.equal('debug,develop');
+    expect(result.client_host).to.equal('host.lando.internal');
+  });
+
+  it('should pass through an object with defaults', () => {
+    const result = normalizeXdebugConfig({mode: 'profile'});
+    expect(result.mode).to.equal('profile');
+    expect(result.start_with_request).to.equal('trigger');
+    expect(result.client_port).to.equal(9003);
+    expect(result.config).to.deep.equal({});
+  });
+
+  it('should resolve client_host auto to host.lando.internal', () => {
+    const result = normalizeXdebugConfig({mode: 'debug', client_host: 'auto'});
+    expect(result.client_host).to.equal('host.lando.internal');
+  });
+
+  it('should allow explicit client_host override', () => {
+    const result = normalizeXdebugConfig({mode: 'debug', client_host: '192.168.1.100'});
+    expect(result.client_host).to.equal('192.168.1.100');
+  });
+
+  it('should merge config pass-through', () => {
+    const result = normalizeXdebugConfig({mode: 'debug', config: {max_nesting_level: 256}});
+    expect(result.config).to.deep.equal({max_nesting_level: 256});
+  });
+
+  it('should apply all defaults for missing keys', () => {
+    const result = normalizeXdebugConfig({mode: 'debug'});
+    expect(result.start_with_request).to.equal('trigger');
+    expect(result.client_host).to.equal('host.lando.internal');
+    expect(result.client_port).to.equal(9003);
+    expect(result.log).to.equal('/tmp/xdebug.log');
+    expect(result.idekey).to.equal('');
+  });
+});
+
+describe('generateXdebugIni', () => {
+  it('should generate valid ini with all settings', () => {
+    const config = {
+      mode: 'debug',
+      start_with_request: 'yes',
+      client_host: 'host.lando.internal',
+      client_port: 9003,
+      log: '/tmp/xdebug.log',
+      idekey: 'LANDO',
+      config: {max_nesting_level: 256},
+    };
+    const ini = generateXdebugIni(config);
+    expect(ini).to.contain('xdebug.mode = debug');
+    expect(ini).to.contain('xdebug.start_with_request = yes');
+    expect(ini).to.contain('xdebug.client_host = host.lando.internal');
+    expect(ini).to.contain('xdebug.client_port = 9003');
+    expect(ini).to.contain('xdebug.log = /tmp/xdebug.log');
+    expect(ini).to.contain('xdebug.idekey = LANDO');
+    expect(ini).to.contain('xdebug.max_nesting_level = 256');
+  });
+
+  it('should omit log when false', () => {
+    const config = {
+      mode: 'debug',
+      start_with_request: 'trigger',
+      client_host: 'host.lando.internal',
+      client_port: 9003,
+      log: false,
+      idekey: '',
+      config: {},
+    };
+    const ini = generateXdebugIni(config);
+    expect(ini).to.not.contain('xdebug.log');
+  });
+
+  it('should omit idekey when empty', () => {
+    const config = {
+      mode: 'debug',
+      start_with_request: 'trigger',
+      client_host: 'host.lando.internal',
+      client_port: 9003,
+      log: '/tmp/xdebug.log',
+      idekey: '',
+      config: {},
+    };
+    const ini = generateXdebugIni(config);
+    expect(ini).to.not.contain('xdebug.idekey');
+  });
+});

From afd05fd05bc27c09f0417b0dd047b66b86424d53 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 21:55:18 -0500
Subject: [PATCH 12/21] docs: rewrite xdebug documentation for new features

---
 docs/config.md | 181 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 145 insertions(+), 36 deletions(-)

diff --git a/docs/config.md b/docs/config.md
index 68d0ea7d..5338f15c 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -84,80 +84,189 @@ services:
     webroot: docroot
 ```
 
-## Using xdebug
+## Using Xdebug
 
-You can enable the `xdebug` extension by setting `xdebug: true` and doing a `lando rebuild`. When the extension is enabled Lando will automatically set the needed configuration for remote debugging. This means that `xdebug` _should_ be ready to receive connections out of the box.
+Xdebug is pre-installed in all Lando PHP images but disabled by default for performance. You can enable it in several ways.
 
-If you are using `xdebug` version 3, which is installed by default for `php` 7.2+ you can optionally specify the mode.
+### Quick start
+
+The simplest way to enable Xdebug is:
 
 ```yaml
 services:
   myservice:
     type: php:8.4
-    xdebug: "debug,develop"
+    xdebug: true
 ```
 
-For this version of `xdebug` setting `xdebug: true` will set `xdebug.mode=debug`. You can read more about `xdebug.mode` [here](https://xdebug.org/docs/all_settings#mode).
-
-### Configuring xdebug
+This sets `xdebug.mode=debug` and configures Xdebug to connect back to your host machine automatically. Run `lando rebuild` after changing this setting.
 
-If you'd like to override Lando's out of the box `xdebug` config the easiest way to do that is by setting the `XDEBUG_CONFIG` environment variable as a service level override.
+You can also specify the [Xdebug mode](https://xdebug.org/docs/all_settings#mode) directly:
 
 ```yaml
 services:
   myservice:
     type: php:8.4
     xdebug: "debug,develop"
-    overrides:
-      environment:
-        XDEBUG_CONFIG: "discover_client_host=0 client_host=localhost"
 ```
 
-Note that you cannot set _every_ `xdebug` configuration option via `XDEBUG_CONFIG`, see [this](https://xdebug.org/docs/all_settings). If you need to configure something outside of the scope of `XDEBUG_CONFIG` we recommend you use a custom `php.ini`.
+### Toggling Xdebug without rebuilding
+
+Xdebug adds overhead to every PHP request. Rather than leaving it on all the time, you can toggle it instantly:
+
+```bash
+# Enable step debugging
+lando xdebug debug
+
+# Enable debugging + development helpers
+lando xdebug debug,develop
+
+# Enable profiling
+lando xdebug profile
+
+# Disable Xdebug
+lando xdebug off
+
+# Check current status
+lando xdebug
+```
+
+These commands take effect immediately — no rebuild required. They work by writing to an ini file and reloading the web server.
+
+::: tip Performance tip
+Set `xdebug: false` in your `.lando.yml` and use `lando xdebug debug` only when you need it. This gives you full speed by default and instant debugging when needed.
+:::
+
+### Advanced configuration
 
-You can also modify or unset `XDEBUG_MODE` in a similar way. For example if you wanted to manage `xdebug.mode` in your own `php.ini` you could so something like
+For fine-grained control, use the object format:
 
 ```yaml
 services:
   myservice:
     type: php:8.4
-    xdebug: true
-    overrides:
-      environment:
-        XDEBUG_MODE:
-    config:
-      php: config/php.ini
+    xdebug:
+      mode: debug
+      start_with_request: "yes"
+      client_host: auto
+      client_port: 9003
+      log: /tmp/xdebug.log
+      idekey: LANDO
+      config:
+        max_nesting_level: 256
 ```
 
-### Setting up your IDE for XDEBUG
+| Option | Default | Description |
+|--------|---------|-------------|
+| `mode` | `off` | Xdebug mode(s). See [xdebug.mode](https://xdebug.org/docs/all_settings#mode). |
+| `start_with_request` | `trigger` | When to start debugging. `trigger` requires a browser extension or `XDEBUG_SESSION` cookie. `yes` starts on every request. |
+| `client_host` | `auto` | Host for Xdebug to connect to. `auto` uses `host.lando.internal` which works on all platforms including WSL2. |
+| `client_port` | `9003` | Port your IDE listens on. |
+| `log` | `/tmp/xdebug.log` | Log file path, or `false` to disable logging. |
+| `idekey` | _(empty)_ | IDE key for filtering debug sessions. |
+| `config` | `{}` | Pass-through for any [Xdebug setting](https://xdebug.org/docs/all_settings). Keys are prefixed with `xdebug.` automatically. |
 
-While Lando will handle the server side configuration for you, there is often a considerable amount of pain lurking in the client side configuration. To that end, some helpful info about a few popular clients is shown below:
+All options are optional. Omitted keys use the defaults shown above.
 
-**PHPStorm**
+::: tip Backward compatibility
+The boolean (`true`/`false`) and string (`"debug,develop"`) formats continue to work exactly as before. The object format is additive.
+:::
 
-[Lando + PhpStorm + Xdebug](https://docs.lando.dev/guides/lando-phpstorm.html)
+### Checking Xdebug configuration
 
-**VSCODE**
+You can view your Xdebug configuration in the `lando info` output:
 
-[Setup XDebug in Visual Studio Code Guide](https://docs.lando.dev/guides/lando-with-vscode.html)
+```bash
+lando info -s myservice --deep
+```
 
-### Troubleshooting Xdebug
+This will show the current Xdebug mode, client host, client port, and other settings.
 
-::: tip Problems starting XDEBUG
-If you are visiting your site and xdebug is not triggering, it might be worth appending `?XDEBUG_SESSION_START=LANDO` to your request and seeing if that does the trick.
-:::
+### Setting up your IDE
+
+Lando configures Xdebug to connect to your host on port `9003` by default. Here's how to set up your IDE:
+
+#### Visual Studio Code
 
-If you have set `xdebug: true` in your recipe or service config and run `lando rebuild` but are still having issues getting `xdebug` to work correctly, we recommend that you remove `xdebug: true`, run `lando rebuild` and then set the relevant `xdebug` config directly using a custom a `php.ini` (see examples above on how to set a custom config file). Your config file should minimally include something as shown below:
+Install the [PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) and add this to `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen for Xdebug",
+      "type": "php",
+      "request": "launch",
+      "port": 9003,
+      "pathMappings": {
+        "/app/": "${workspaceFolder}/"
+      }
+    }
+  ]
+}
+```
+
+#### PhpStorm
+
+1. Go to **Settings → PHP → Debug** and set the Xdebug port to `9003`
+2. Go to **Settings → PHP → Servers**, add a server named `appserver` (or your service name)
+3. Set the host to your Lando app URL and map your project root to `/app`
+4. Click **Start Listening for PHP Debug Connections** in the toolbar
+
+See also: [Lando + PhpStorm + Xdebug Guide](https://docs.lando.dev/guides/lando-phpstorm.html)
+
+### Using with a browser extension
+
+When `start_with_request` is set to `trigger` (the default), you need a browser extension to activate Xdebug:
+
+- **Chrome/Edge:** [Xdebug Helper](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc)
+- **Firefox:** [Xdebug Helper](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/)
+
+Alternatively, append `?XDEBUG_SESSION_START=LANDO` to any URL to start a debug session.
+
+If you prefer Xdebug to activate on every request without a browser extension:
 
 ```yaml
-xdebug.max_nesting_level = 256
-xdebug.show_exception_trace = 0
-xdebug.collect_params = 0
-xdebug.remote_enable = 1
-xdebug.remote_host = YOUR HOST IP ADDRESS
+services:
+  myservice:
+    type: php:8.4
+    xdebug:
+      mode: debug
+      start_with_request: "yes"
 ```
 
-You can use `lando info --deep | grep IPAddress` to help discover the correct host ip address but please note that this can change and will likely differ from dev to dev.
+### Overriding via environment variables
+
+You can still override Xdebug settings using environment variables if needed:
+
+```yaml
+services:
+  myservice:
+    type: php:8.4
+    xdebug: true
+    overrides:
+      environment:
+        XDEBUG_CONFIG: "discover_client_host=0 client_host=localhost"
+```
+
+Note that you cannot set _every_ Xdebug configuration option via `XDEBUG_CONFIG`. See the [Xdebug documentation](https://xdebug.org/docs/all_settings) for details. For full control, use the object config format above or a custom `php.ini`.
+
+### Troubleshooting
+
+**Xdebug not triggering?**
+- Check that your IDE is listening on port `9003`
+- Try `lando xdebug` to verify Xdebug is enabled and check the current mode
+- Try appending `?XDEBUG_SESSION_START=LANDO` to your URL
+- Check `/tmp/xdebug.log` inside the container for connection errors: `lando exec myservice -- cat /tmp/xdebug.log`
+
+**Connection refused?**
+- Lando uses `host.lando.internal` to connect back to your host. This should work on macOS, Linux, and WSL2.
+- If you're on an unusual setup, try setting `client_host` explicitly in the config object.
+
+**Slow performance?**
+- Use `lando xdebug off` when you're not actively debugging.
+- Or set `xdebug: false` in your Landofile and toggle with `lando xdebug debug` only when needed.
 
 ## Installing composer
 

From 4af9cdfe1b5ccfee8f855cbc19d1ab432abe2b07 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 22:01:09 -0500
Subject: [PATCH 13/21] fix: update Chrome Web Store URL to new domain

---
 docs/config.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/config.md b/docs/config.md
index 5338f15c..00994301 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -220,7 +220,7 @@ See also: [Lando + PhpStorm + Xdebug Guide](https://docs.lando.dev/guides/lando-
 
 When `start_with_request` is set to `trigger` (the default), you need a browser extension to activate Xdebug:
 
-- **Chrome/Edge:** [Xdebug Helper](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc)
+- **Chrome/Edge:** [Xdebug Helper](https://chromewebstore.google.com/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc)
 - **Firefox:** [Xdebug Helper](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/)
 
 Alternatively, append `?XDEBUG_SESSION_START=LANDO` to any URL to start a debug session.

From 18cef1472e40726803cea10917ecece0781f46e9 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 17 Mar 2026 03:19:40 +0000
Subject: [PATCH 14/21] Fix xdebug env var precedence issues

- 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
---
 builders/php.js | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/builders/php.js b/builders/php.js
index cd1b4d03..cff820ac 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -51,15 +51,15 @@ const nginxConfig = options => ({
   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 @@ const phpBuilder = {
         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'] : [],

From 86b549600d67b7caefb3d575f9d0a516f41a67d8 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 22:35:37 -0500
Subject: [PATCH 15/21] =?UTF-8?q?fix:=20CI=20test=20failures=20=E2=80=94?=
 =?UTF-8?q?=20xdebug.sh=20reload=20logic=20and=20leia=20test=20assertions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 examples/xdebug/README.md | 16 ++++++++--------
 scripts/xdebug.sh         |  8 ++++++--
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
index 0aff2f33..0e6acf41 100644
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -23,7 +23,7 @@ Run the following commands to validate things are rolling as they should.
 
 ```bash
 # Should not have xdebug 2 deprecation warnings
-lando exec xdebug-true -- php -v 2>&1 | grep -c "has been renamed\|remote_autostart" | grep 0
+lando exec xdebug-true -- php -v 2>&1 | grep "has been renamed\|remote_autostart" && exit 1 || true
 
 # Should use host.lando.internal in XDEBUG_CONFIG
 lando exec xdebug-true -- env | grep XDEBUG_CONFIG | grep host.lando.internal
@@ -39,29 +39,29 @@ lando exec xdebug-true -- test -f /etc/lando/service/helpers/xdebug.sh
 
 # Should be able to toggle xdebug off at runtime
 lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh off
-lando exec xdebug-true -- php -r "echo ini_get('xdebug.mode');" | grep off
+lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep off
 
 # Should be able to toggle xdebug back on
 lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh debug
-lando exec xdebug-true -- php -r "echo ini_get('xdebug.mode');" | grep debug
+lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep debug
 
 # Should show status with no arguments
 lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh | grep -i "mode"
 
 # Should enable xdebug when set to true (backward compat)
-lando exec xdebug-true -- php -r "echo ini_get('xdebug.mode');" | grep debug
+lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set mode from string (backward compat)
-lando exec xdebug-string -- php -r "echo ini_get('xdebug.mode');" | grep "debug,develop"
+lando exec xdebug-string -- env | grep XDEBUG_MODE | grep "debug,develop"
 
 # Should set mode from object config
-lando exec xdebug-object -- php -r "echo ini_get('xdebug.mode');" | grep debug
+lando exec xdebug-object -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set start_with_request from object config
-lando exec xdebug-object -- php -r "echo ini_get('xdebug.start_with_request');" | grep yes
+lando exec xdebug-object -- php -i | grep "xdebug.start_with_request" | grep yes
 
 # Should apply config pass-through settings
-lando exec xdebug-passthrough -- php -r "echo ini_get('xdebug.max_nesting_level');" | grep 256
+lando exec xdebug-passthrough -- php -i | grep "xdebug.max_nesting_level" | grep 256
 
 # Should not load xdebug when object mode is off
 lando exec xdebug-off-object -- php -m | grep xdebug || echo $? | grep 1
diff --git a/scripts/xdebug.sh b/scripts/xdebug.sh
index 71815136..29c7f64b 100755
--- a/scripts/xdebug.sh
+++ b/scripts/xdebug.sh
@@ -1,6 +1,6 @@
 #!/bin/sh
 
-set -eu
+set -u
 
 XDEBUG_INI="/usr/local/etc/php/conf.d/zzz-lando-xdebug.ini"
 GREEN='\033[0;32m'
@@ -9,7 +9,11 @@ BLUE='\033[0;34m'
 NC='\033[0m'
 
 reload_web_server() {
-  kill -USR2 "$(pgrep -o php-fpm)" 2>/dev/null || /etc/init.d/apache2 reload 2>/dev/null || true
+  if pgrep -o php-fpm >/dev/null 2>&1; then
+    kill -USR2 "$(pgrep -o php-fpm)" 2>/dev/null || true
+  elif [ -f /etc/init.d/apache2 ]; then
+    /etc/init.d/apache2 reload 2>/dev/null || true
+  fi
 }
 
 print_usage() {

From e824d06741f766d5293e538b6e8978436002f372 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 17 Mar 2026 04:34:37 +0000
Subject: [PATCH 16/21] Fix test to check xdebug mode via php -i instead of
 XDEBUG_MODE env var

Applied via @cursor push command
---
 examples/xdebug/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
index 0e6acf41..512c48a5 100644
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -52,7 +52,7 @@ lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh | grep -i "mode"
 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

From 7d543ee26eadf7739f89fe2349e91467e7177df4 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Mon, 16 Mar 2026 23:36:01 -0500
Subject: [PATCH 17/21] fix: pin swoole version in php-extensions test (6.2.0
 compile failure)

---
 examples/php-extensions/.lando.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/php-extensions/.lando.yml b/examples/php-extensions/.lando.yml
index 8537bbdb..a1f99857 100644
--- a/examples/php-extensions/.lando.yml
+++ b/examples/php-extensions/.lando.yml
@@ -3,7 +3,7 @@ services:
   83scripted:
     type: php:8.3
     build_as_root:
-      - install-php-extensions swoole
+      - install-php-extensions swoole-5.1.6
   buildsteps:
     type: php:8.3
     build_as_root:

From a650420f1a1c5aef620dd3e9c142546094bab4f4 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Tue, 17 Mar 2026 18:43:58 -0500
Subject: [PATCH 18/21] Fix flaky xdebug leia assertions

---
 examples/xdebug/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
index 512c48a5..30ca6811 100644
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -39,7 +39,7 @@ lando exec xdebug-true -- test -f /etc/lando/service/helpers/xdebug.sh
 
 # Should be able to toggle xdebug off at runtime
 lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh off
-lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep off
+lando exec xdebug-true -- grep "xdebug.mode = off" /usr/local/etc/php/conf.d/zzz-lando-xdebug.ini
 
 # Should be able to toggle xdebug back on
 lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh debug
@@ -52,13 +52,13 @@ lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh | grep -i "mode"
 lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set mode from string (backward compat)
-lando exec xdebug-string -- php -i | grep "xdebug.mode" | grep "debug,develop"
+lando exec xdebug-string -- grep "xdebug.mode = debug,develop" /usr/local/etc/php/conf.d/yyy-lando-xdebug.ini
 
 # Should set mode from object config
 lando exec xdebug-object -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set start_with_request from object config
-lando exec xdebug-object -- php -i | grep "xdebug.start_with_request" | grep yes
+lando exec xdebug-object -- grep "xdebug.start_with_request = yes" /usr/local/etc/php/conf.d/yyy-lando-xdebug.ini
 
 # Should apply config pass-through settings
 lando exec xdebug-passthrough -- php -i | grep "xdebug.max_nesting_level" | grep 256

From aa0862244d6871f417217b9e4bfc837ee0f8f2ae Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Tue, 17 Mar 2026 18:52:11 -0500
Subject: [PATCH 19/21] Stabilize xdebug config leia checks

---
 examples/xdebug/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/xdebug/README.md b/examples/xdebug/README.md
index 30ca6811..08f9fcc7 100644
--- a/examples/xdebug/README.md
+++ b/examples/xdebug/README.md
@@ -52,13 +52,13 @@ lando exec xdebug-true -- /etc/lando/service/helpers/xdebug.sh | grep -i "mode"
 lando exec xdebug-true -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set mode from string (backward compat)
-lando exec xdebug-string -- grep "xdebug.mode = debug,develop" /usr/local/etc/php/conf.d/yyy-lando-xdebug.ini
+lando info -s xdebug-string --deep | grep "debug,develop"
 
 # Should set mode from object config
 lando exec xdebug-object -- php -i | grep "xdebug.mode" | grep debug
 
 # Should set start_with_request from object config
-lando exec xdebug-object -- grep "xdebug.start_with_request = yes" /usr/local/etc/php/conf.d/yyy-lando-xdebug.ini
+lando info -s xdebug-object --deep | grep start_with_request | grep yes
 
 # Should apply config pass-through settings
 lando exec xdebug-passthrough -- php -i | grep "xdebug.max_nesting_level" | grep 256

From f2bb200f63abbc0fa70de6a68efcd41128c2f73b Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 18 Mar 2026 04:11:49 +0000
Subject: [PATCH 20/21] Fix: Always generate xdebug ini file to persist custom
 settings

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
---
 builders/php.js | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/builders/php.js b/builders/php.js
index cff820ac..87d1e08e 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -285,12 +285,10 @@ const phpBuilder = {
 
       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) {

From 89a5d679c2f0a00fa1ddfb29a190abe30ada19a2 Mon Sep 17 00:00:00 2001
From: Aaron Feledy <aaron@arrow.one>
Date: Tue, 17 Mar 2026 23:52:52 -0500
Subject: [PATCH 21/21] Fix xdebug ini generation and add clarifying comments

- 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.
---
 builders/php.js   | 50 +++++++++++++++++++++++++++++------------------
 scripts/xdebug.sh |  3 +++
 2 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/builders/php.js b/builders/php.js
index 87d1e08e..71bea069 100644
--- a/builders/php.js
+++ b/builders/php.js
@@ -101,23 +101,24 @@ const normalizeXdebugConfig = xdebug => {
  * @return {string} The generated xdebug ini contents.
  */
 const generateXdebugIni = config => {
-  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}`,
-  ];
-
-  if (config.log !== false) ini.push(`xdebug.log = ${config.log}`);
-  if (!_.isEmpty(config.idekey)) ini.push(`xdebug.idekey = ${config.idekey}`);
-
-  _.forEach(config.config, (value, key) => {
-    ini.push(`xdebug.${key} = ${value}`);
-  });
-
-  return `${ini.join('\n')}\n`;
+  // Build as ordered map so config pass-through can override defaults without duplicates
+  const settings = new Map([
+    ['mode', config.mode],
+    ['max_nesting_level', 512],
+    ['start_with_request', config.start_with_request],
+    ['client_host', config.client_host],
+    ['client_port', config.client_port],
+  ]);
+
+  if (config.log !== false) settings.set('log', config.log);
+  if (!_.isEmpty(config.idekey)) settings.set('idekey', config.idekey);
+
+  // config pass-through: overrides defaults if keys overlap, appends otherwise
+  _.forEach(config.config, (value, key) => settings.set(key, value));
+
+  const lines = ['; Generated by Lando PHP plugin'];
+  settings.forEach((value, key) => lines.push(`xdebug.${key} = ${value}`));
+  return `${lines.join('\n')}\n`;
 };
 
 const detectDatabaseClient = (options, debug = () => {}) => {
@@ -235,6 +236,13 @@ const phpBuilder = {
     command: ['sh -c \'a2enmod rewrite headers expires && apache2-foreground\''],
     composer_version: true,
     phpServer: 'apache',
+    // PHP loads conf.d ini files alphabetically. We use filename prefixes to control load order:
+    //   xxx-lando-default.ini  — base PHP settings
+    //   yyy-lando-xdebug.ini   — generated xdebug config from .lando.yml (host-mounted)
+    //   zzz-lando-xdebug.ini   — runtime mode override written by `lando xdebug` toggle (container-only)
+    //   zzz-lando-my-custom.ini — user custom php.ini overrides
+    // The zzz toggle file intentionally only contains xdebug.mode so it can override the yyy config
+    // at runtime without clobbering other xdebug settings (client_port, idekey, etc).
     defaultFiles: {
       _php: 'php.ini',
       xdebug: 'yyy-lando-xdebug.ini',
@@ -286,8 +294,12 @@ const phpBuilder = {
       options._xdebugConfig = normalizeXdebugConfig(options.xdebug);
       options.xdebug = options._xdebugConfig.mode;
       const xdebugFile = path.join(options.confDest, options.defaultFiles.xdebug);
-      fs.mkdirSync(options.confDest, {recursive: true});
-      fs.writeFileSync(xdebugFile, generateXdebugIni(options._xdebugConfig));
+      try {
+        fs.mkdirSync(options.confDest, {recursive: true});
+        fs.writeFileSync(xdebugFile, generateXdebugIni(options._xdebugConfig));
+      } catch (err) {
+        throw new Error(`Failed to write xdebug config to ${xdebugFile}: ${err.message}`);
+      }
       options.volumes.push(`${xdebugFile}:${options.remoteFiles.xdebug}`);
 
       options._app.config.tooling = options._app.config.tooling || {};
diff --git a/scripts/xdebug.sh b/scripts/xdebug.sh
index 29c7f64b..d44ab3c7 100755
--- a/scripts/xdebug.sh
+++ b/scripts/xdebug.sh
@@ -2,6 +2,9 @@
 
 set -u
 
+# This is a runtime override file, separate from the host-mounted yyy-lando-xdebug.ini which
+# holds the full xdebug config from .lando.yml. The zzz prefix ensures this loads after yyy,
+# so writing only xdebug.mode here overrides the mode without clobbering other settings.
 XDEBUG_INI="/usr/local/etc/php/conf.d/zzz-lando-xdebug.ini"
 GREEN='\033[0;32m'
 RED='\033[0;31m'