Fix --php override for xback so DebugServer can spawn the override binary

CodeRabbit flagged that bin/xback's --php option replaced $command[0]
with the resolved override path, but DebugServer::executeTargetScript()
selects the local-PHP execution branch via a strict $command[0] === 'php'
check and otherwise throws "Custom command must start with 'php' or be a
Docker/Podman/Kubectl command". Even if the check were loosened, the cmd
template hardcoded the literal 'php' token, so the override would never
be exec'd anyway.

Plumb the override through DebugServer's options as `phpBinary` instead:
xback keeps $command[0] as the literal 'php', and DebugServer substitutes
the option (escapeshellarg-quoted) into both the local-command and
default-script command templates, defaulting to 'php' when unset.

Adds testXbackPhpOption that runs `xback --php=<absolute php> -- php
<fixture>` and asserts the run doesn't fall through to the error path
and emits the expected xback JSON.

Author: koriym

bin/xback

@@ -187,16 +187,17 @@ function outputBacktraceJson(string $script, ?string $breakpointStr, string $con
     // Detect Docker/Podman/Kubectl commands
     $isDockerCommand = \Koriym\XdebugMcp\ContainerHelper::isContainerCommand($command);
 
-    // Apply --php override to local commands whose first token is a PHP binary.
-    if (
+    // Decide whether the --php override should apply to the local command.
+    // Keep $command[0] as the literal 'php' so DebugServer's strict-equality
+    // check still selects the local-PHP execution branch; the actual override
+    // path is plumbed through DebugServer's `phpBinary` option below.
+    $applyPhpOverride = (
         !$isDockerCommand
         && $phpOverride !== null
         && $phpOverride !== ''
         && !empty($command)
         && \Koriym\XdebugMcp\XdebugRunner::isPhpBinary($command[0])
-    ) {
-        $command[0] = $phpOverride;
-    }
+    );
 
     // Parse breakpoint now that we know if it's a Docker command
     if ($breakpointStr !== null) {
@@ -248,6 +249,10 @@ function outputBacktraceJson(string $script, ?string $breakpointStr, string $con
         'maxSteps' => 1,
     ];
 
+    if ($applyPhpOverride) {
+        $options['phpBinary'] = $phpOverride;
+    }
+
     // Capture DebugServer output
     ob_start();
     $server = new DebugServer($targetScript, Constants::XDEBUG_DEBUG_PORT, null, $options, true);

src/DebugServer.php

@@ -354,8 +354,14 @@ private function executeTargetScript(): void
                     $xdebugFlag = XdebugFinder::getXdebugFlag();
                     $xdebugPart = $xdebugFlag !== '' ? $xdebugFlag . ' ' : '';
 
+                    // Allow callers (e.g. xback --php=...) to override the spawned
+                    // PHP binary while keeping $command[0] as the literal 'php'.
+                    $phpBinary = ($this->options['phpBinary'] ?? '') !== ''
+                        ? (string) $this->options['phpBinary']
+                        : 'php';
+
                     $cmd = sprintf(
-                        'XDEBUG_SESSION=xdebug-mcp php %s'
+                        'XDEBUG_SESSION=xdebug-mcp %s %s'
                         . '-dxdebug.mode=debug,trace '
                         . '-dxdebug.start_with_request=yes '
                         . '-dxdebug.client_host=127.0.0.1 '
@@ -372,6 +378,7 @@ private function executeTargetScript(): void
                         . '-derror_log=/tmp/php.log '
                         . '-dauto_prepend_file=%s '
                         . '%s',
+                        escapeshellarg($phpBinary),
                         $xdebugPart,
                         $this->debugPort,
                         escapeshellarg($prependFilter),
@@ -391,8 +398,13 @@ private function executeTargetScript(): void
                 $xdebugFlag = XdebugFinder::getXdebugFlag();
                 $xdebugPart = $xdebugFlag !== '' ? $xdebugFlag . ' ' : '';
 
+                // Honor an optional PHP-binary override.
+                $phpBinary = ($this->options['phpBinary'] ?? '') !== ''
+                    ? (string) $this->options['phpBinary']
+                    : 'php';
+
                 $cmd = sprintf(
-                    'XDEBUG_SESSION=xdebug-mcp php %s'
+                    'XDEBUG_SESSION=xdebug-mcp %s %s'
                     . '-dxdebug.mode=debug,trace '
                     . '-dxdebug.start_with_request=yes '
                     . '-dxdebug.client_host=127.0.0.1 '
@@ -405,6 +417,7 @@ private function executeTargetScript(): void
                     . '-dxdebug.connect_timeout_ms=5000 '
                     . '-dauto_prepend_file=%s '
                     . '%s',
+                    escapeshellarg($phpBinary),
                     $xdebugPart,
                     $this->debugPort,
                     escapeshellarg($prependFilter),

tests/Integration/XdebugCommandsTest.php

@@ -34,6 +34,7 @@
 use function var_export;
 
 use const JSON_THROW_ON_ERROR;
+use const PHP_BINARY;
 
 class XdebugCommandsTest extends TestCase
 {
@@ -412,6 +413,48 @@ public function testXbackCwdOption(): void
         $this->assertArrayHasKey('$schema', $payload);
     }
 
+    public function testXbackPhpOption(): void
+    {
+        if (! XdebugFinder::isXdebugAvailable()) {
+            $this->markTestSkipped('Xdebug not available');
+        }
+
+        // Resolve the current PHP binary as the override target. Using PHP_BINARY
+        // guarantees the path exists and is executable on the running system.
+        $phpBinary = realpath(PHP_BINARY);
+        if ($phpBinary === false || ! is_executable($phpBinary)) {
+            $this->markTestSkipped('Cannot resolve PHP_BINARY for --php override test');
+        }
+
+        $fixture = dirname(__DIR__) . '/fixtures/print_cwd.php';
+
+        // Run with --php pointing at an absolute PHP binary path. Without the
+        // fix this fails with "Custom command must start with 'php' or be a
+        // Docker/Podman/Kubectl command" because $command[0] becomes the
+        // absolute path and DebugServer's strict-equality check rejects it.
+        $command = sprintf(
+            'cd %s && ./bin/xback --php=%s -- php %s 2>&1',
+            escapeshellarg(dirname(__DIR__, 2)),
+            escapeshellarg($phpBinary),
+            escapeshellarg($fixture),
+        );
+
+        $output = shell_exec($command);
+        $this->assertNotNull($output);
+        $this->assertStringNotContainsString(
+            "must start with 'php'",
+            $output,
+            '--php override should not fall through to the DebugServer error path',
+        );
+
+        $jsonStart = strrpos($output, '{"$schema"');
+        $this->assertNotFalse($jsonStart, $output);
+
+        $payload = json_decode(substr($output, $jsonStart), true, 512, JSON_THROW_ON_ERROR);
+        $this->assertIsArray($payload);
+        $this->assertArrayHasKey('$schema', $payload);
+    }
+
     public function testAllCommandsAreExecutable(): void
     {
         $commands = [