Setting port=0 will use a random port and pass that to either env or runtimeArgs.

Author: zobo

package.json

@@ -202,7 +202,7 @@
               "port": {
                 "type": "number",
                 "description": "Port on which to listen for Xdebug",
-                "default": 9000
+                "default": 9003
               },
               "serverSourceRoot": {
                 "type": "string",
@@ -261,15 +261,70 @@
             "name": "Listen for Xdebug",
             "type": "php",
             "request": "launch",
-            "port": 9000
+            "port": 9003
           },
           {
             "name": "Launch currently open script",
             "type": "php",
             "request": "launch",
             "program": "${file}",
             "cwd": "${fileDirname}",
-            "port": 9000
+            "port": 0,
+            "runtimeArgs": [
+              "-dxdebug.start_with_request=yes"
+            ],
+            "env": {
+              "XDEBUG_MODE": "debug,develop",
+              "XDEBUG_CONFIG": "client_port=${port}"
+            }
+          }
+        ],
+        "configurationSnippets": [
+          {
+            "label": "PHP: Listen for Xdebug",
+            "description": "Listening for Xdebug",
+            "body": {
+              "name": "Listen for Xdebug",
+              "type": "php",
+              "request": "launch",
+              "port": 9003
+            }
+          },
+          {
+            "label": "PHP: Launch currently open script",
+            "description": "Launch currently open script",
+            "body": {
+              "name": "Launch currently open script",
+              "type": "php",
+              "request": "launch",
+              "program": "^\"${1:\\${file\\}}\"",
+              "cwd": "^\"${2:\\${fileDirname\\}}\"",
+              "port": 0,
+              "runtimeArgs": [
+                "-dxdebug.start_with_request=yes"
+                ],
+                "env": {
+                  "XDEBUG_MODE": "debug,develop",
+                  "XDEBUG_CONFIG": "^\"client_port=\\${port\\}\""
+                }
+              }
+          },
+          {
+            "label": "PHP: Launch currently open script with Xdebug 2",
+            "description": "Launch currently open script",
+            "body": {
+              "name": "Launch currently open script",
+              "type": "php",
+              "request": "launch",
+              "program": "^\"${1:\\${file\\}}\"",
+              "cwd": "^\"${2:\\${fileDirname\\}}\"",
+              "port": 0,
+              "runtimeArgs": [
+                "-dxdebug.remote_enable=1",
+                "-dxdebug.remote_autostart=1",
+                "^\"-dxdebug.remote_port=\\${port\\}\""
+              ]
+            }
           }
         ]
       }

src/phpDebug.ts

@@ -205,16 +205,18 @@ class PhpDebugSession extends vscode.DebugSession {
         }
         this._args = args
         /** launches the script as CLI */
-        const launchScript = async () => {
+        const launchScript = async (port: number) => {
             // check if program exists
             await new Promise<void>((resolve, reject) =>
                 fs.access(args.program!, fs.constants.F_OK, err => (err ? reject(err) : resolve()))
             )
-            const runtimeArgs = args.runtimeArgs || []
+            const runtimeArgs = (args.runtimeArgs || []).map(v => v.replace('${port}', port.toString()))
             const runtimeExecutable = args.runtimeExecutable || 'php'
             const programArgs = args.args || []
             const cwd = args.cwd || process.cwd()
-            const env = args.env || process.env
+            const env = Object.fromEntries(
+                Object.entries(args.env || process.env).map(v => [v[0], v[1]?.replace('${port}', port.toString())])
+            )
             // launch in CLI mode
             if (args.externalConsole) {
                 const script = await Terminal.launchInTerminal(
@@ -252,7 +254,7 @@ class PhpDebugSession extends vscode.DebugSession {
         }
         /** sets up a TCP server to listen for Xdebug connections */
         const createServer = () =>
-            new Promise<void>((resolve, reject) => {
+            new Promise<number>((resolve, reject) => {
                 const server = (this._server = net.createServer())
                 server.on('connection', async (socket: net.Socket) => {
                     try {
@@ -316,16 +318,22 @@ class PhpDebugSession extends vscode.DebugSession {
                 })
                 server.on('error', (error: Error) => {
                     this.sendEvent(new vscode.OutputEvent(util.inspect(error) + '\n'))
-                    this.sendErrorResponse(response, <Error>error)
+                    reject(error)
+                })
+                server.on('listening', () => {
+                    const port = (server.address() as net.AddressInfo).port
+                    resolve(port)
                 })
-                server.listen(args.port || 9000, args.hostname, () => resolve())
+                const listenPort = args.port === undefined ? 9000 : args.port
+                server.listen(listenPort, args.hostname)
             })
         try {
+            let port = 0
             if (!args.noDebug) {
-                await createServer()
+                port = await createServer()
             }
             if (args.program) {
-                await launchScript()
+                await launchScript(port)
             }
         } catch (error) {
             this.sendErrorResponse(response, <Error>error)

testproject/.vscode/launch.json

@@ -1,22 +1,30 @@
 {
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
     {
       //"debugServer": 4711, // Uncomment for debugging the adapter
       "name": "Listen for Xdebug",
       "type": "php",
       "request": "launch",
-      "port": 9000,
+      "port": 9003,
       "log": true
     },
     {
       //"debugServer": 4711, // Uncomment for debugging the adapter
-      "name": "Launch",
-      "request": "launch",
+      "name": "Launch currently open script",
       "type": "php",
+      "request": "launch",
       "program": "${file}",
-      "cwd": "${workspaceRoot}",
-      "externalConsole": false
+      "cwd": "${fileDirname}",
+      "port": 0,
+      "runtimeArgs": ["-dxdebug.start_with_request=yes"],
+      "env": {
+        "XDEBUG_MODE": "debug,develop",
+        "XDEBUG_CONFIG": "client_port=${port}"
+      }
     }
   ]
 }

tsconfig.json

@@ -1,7 +1,7 @@
 {
   "include": ["src/**/*"],
   "compilerOptions": {
-    "target": "es6",
+    "target": "es2019",
     "module": "commonjs",
     "rootDir": "src",
     "outDir": "out",