Prewire Xdebug for workspace use

Xdebug is already baked in but unconfigured, which meant users had to
hand-write ini settings every time they wanted to debug against an IDE
on the host.

New scripts/php/xdebug.ini sets mode=off (zero overhead until flipped),
client_host=host.docker.internal, start_with_request=trigger, and
discover_client_host=true. Layered on top of Sury's 20-xdebug.ini via
the 99-xdebug-workspace.ini filename in every SAPI conf.d that loads
xdebug. Staged alongside workspace.ini at /usr/local/share/php-workspace
so pvm applies it to versions installed later too.

With this in place, debugging is just:
  XDEBUG_MODE=debug php app.php
or sending XDEBUG_TRIGGER via cookie/query/env at request time.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chapterjason

scripts/php/install.sh

@@ -45,16 +45,21 @@ rm -rf /var/lib/apt/lists/*
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# Dev-oriented php.ini overrides. Staged at a known path so pvm can reuse
-# it when installing additional PHP versions later.
+# Workspace overrides (dev php.ini + xdebug tuning). Staged at a known
+# path so pvm can reuse them when installing additional PHP versions.
 install -m 0755 -d /usr/local/share/php-workspace
 install -m 0644 "$script_dir/workspace.ini" /usr/local/share/php-workspace/workspace.ini
+install -m 0644 "$script_dir/xdebug.ini"    /usr/local/share/php-workspace/xdebug.ini
 
 # Apply to every SAPI (cli, fpm, apache2, ...) of the default version that
-# got installed. 99- prefix so it loads last and wins over Sury defaults.
+# got installed. 99- prefix so they load last and win over Sury defaults.
+# xdebug override only lands where xdebug is actually enabled for the SAPI.
 for sapi_dir in /etc/php/"$PHP_DEFAULT_VERSION"/*/conf.d; do
   [ -d "$sapi_dir" ] || continue
   install -m 0644 /usr/local/share/php-workspace/workspace.ini "$sapi_dir/99-workspace.ini"
+  if ls "$sapi_dir"/*xdebug.ini >/dev/null 2>&1; then
+    install -m 0644 /usr/local/share/php-workspace/xdebug.ini "$sapi_dir/99-xdebug-workspace.ini"
+  fi
 done
 
 # pvm — user-level PHP version switcher. Lives next to this installer; see

scripts/php/pvm

@@ -130,15 +130,19 @@ cmd_install() {
   # shellcheck disable=SC2086
   sudo apt-get install -y --no-install-recommends --no-install-suggests $pkgs
 
-  # Layer the staged workspace overrides (dev errors, no memory cap, ...)
-  # over every SAPI dir this version created. Staged by scripts/php/install.sh
-  # at image build time.
-  if [ -r /usr/local/share/php-workspace/workspace.ini ]; then
-    for sapi_dir in /etc/php/"$ver"/*/conf.d; do
-      [ -d "$sapi_dir" ] || continue
+  # Layer the staged workspace overrides (dev errors, no memory cap,
+  # xdebug tuning) over every SAPI dir this version created. Staged by
+  # scripts/php/install.sh at image build time. The xdebug overlay only
+  # lands where xdebug is enabled for the SAPI.
+  for sapi_dir in /etc/php/"$ver"/*/conf.d; do
+    [ -d "$sapi_dir" ] || continue
+    if [ -r /usr/local/share/php-workspace/workspace.ini ]; then
       sudo install -m 0644 /usr/local/share/php-workspace/workspace.ini "$sapi_dir/99-workspace.ini"
-    done
-  fi
+    fi
+    if [ -r /usr/local/share/php-workspace/xdebug.ini ] && ls "$sapi_dir"/*xdebug.ini >/dev/null 2>&1; then
+      sudo install -m 0644 /usr/local/share/php-workspace/xdebug.ini "$sapi_dir/99-xdebug-workspace.ini"
+    fi
+  done
 
   echo "PHP $ver installed. Activate with: pvm use $ver"
 }

scripts/php/xdebug.ini

@@ -0,0 +1,17 @@
+; Xdebug defaults for workspace use. Sury's 20-xdebug.ini already loads
+; the extension (zend_extension=xdebug.so) — this file only tunes runtime
+; behavior on top. Loaded via the 99-xdebug-workspace.ini filename so it
+; wins over Sury's own config.
+;
+; mode=off means zero overhead by default: enable per-run with
+;   XDEBUG_MODE=debug php …
+; or per-request with the XDEBUG_TRIGGER cookie / GET / POST / env var.
+;
+; client_host=host.docker.internal targets the Docker host running the
+; workspace container; discover_client_host finds the right IP if the
+; IDE is elsewhere on the network.
+xdebug.mode = off
+xdebug.client_host = host.docker.internal
+xdebug.start_with_request = trigger
+xdebug.discover_client_host = true
+xdebug.log_level = 0