feat: Launch with random port and command line configuration (#588)

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

* Initial configuration and configuration snippets with random port. Command line debug triggers.

* Port description.

* Xdebug 2 configuration snippets

Author: zobo

README.md

@@ -67,7 +67,7 @@ More general information on debugging with VS Code can be found on https://code.
 
 - `request`: Always `"launch"`
 - `hostname`: The address to bind to when listening for Xdebug (default: all IPv6 connections if available, else all IPv4 connections)
-- `port`: The port on which to listen for Xdebug (default: `9003`)
+- `port`: The port on which to listen for Xdebug (default: `9003`). If port is set to `0` a random port is chosen by the system and a placeholder `${port}` is replaced with the chosen port in `env` and `runtimeArgs`.
 - `stopOnEntry`: Whether to break at the beginning of the script (default: `false`)
 - `pathMappings`: A list of server paths mapping to the local source paths on your machine, see "Remote Host Debugging" below
 - `log`: Whether to log all communication between VS Code and the adapter to the debug console. See _Troubleshooting_ further down.

package.json

@@ -279,7 +279,14 @@
             "request": "launch",
             "program": "${file}",
             "cwd": "${fileDirname}",
-            "port": 9003
+            "port": 0,
+            "runtimeArgs": [
+              "-dxdebug.start_with_request=yes"
+            ],
+            "env": {
+              "XDEBUG_MODE": "debug,develop",
+              "XDEBUG_CONFIG": "client_port=${port}"
+            }
           },
           {
             "name": "Launch Built-in web server",
@@ -312,6 +319,16 @@
               "port": 9003
             }
           },
+          {
+            "label": "PHP: Listen for Xdebug 2 (Legacy)",
+            "description": "Listen for incoming XDebug connections on legacy port",
+            "body": {
+              "name": "Listen for Xdebug 2 (Legacy)",
+              "type": "php",
+              "request": "launch",
+              "port": 9000
+            }
+          },
           {
             "label": "PHP: Launch currently open script",
             "description": "Debug the currently open PHP script in CLI mode",
@@ -321,7 +338,33 @@
               "request": "launch",
               "program": "^\"${1:\\${file\\}}\"",
               "cwd": "^\"${2:\\${fileDirname\\}}\"",
-              "port": 9003
+              "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 (Legacy)",
+            "description": "Debug the currently open PHP script in CLI mode",
+            "body": {
+              "name": "Launch currently open script with Xdebug 2 (Legacy)",
+              "type": "php",
+              "request": "launch",
+              "program": "^\"${1:\\${file\\}}\"",
+              "cwd": "^\"${2:\\${fileDirname\\}}\"",
+              "port": 0,
+              "runtimeArgs": [
+                "-dxdebug.remote_enable=yes",
+                "-dxdebug.remote_autostart=yes"
+              ],
+              "env": {
+                "XDEBUG_CONFIG": "^\"remote_port=\\${port\\}\""
+              }
             }
           },
           {

src/phpDebug.ts

@@ -210,19 +210,21 @@ 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
             if (args.program) {
                 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 program = args.program ? [args.program] : []
             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(
@@ -260,7 +262,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 {
@@ -342,16 +344,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 || 9003, args.hostname, () => resolve())
+                const listenPort = args.port === undefined ? 9003 : args.port
+                server.listen(listenPort, args.hostname)
             })
         try {
+            let port = 0
             if (!args.noDebug) {
-                await createServer()
+                port = await createServer()
             }
             if (args.program || args.runtimeArgs) {
-                await launchScript()
+                await launchScript(port)
             }
         } catch (error) {
             this.sendErrorResponse(response, <Error>error)

testproject/.vscode/launch.json

@@ -16,17 +16,28 @@
       "request": "launch",
       "program": "${file}",
       "cwd": "${fileDirname}",
-      "port": 9003
+      "port": 0,
+      "runtimeArgs": ["-dxdebug.start_with_request=yes"],
+      "env": {
+        "XDEBUG_MODE": "debug,develop",
+        "XDEBUG_CONFIG": "client_port=${port}"
+      }
     },
     {
       //"debugServer": 4711, // Uncomment for debugging the adapter
       "name": "Launch Built-in web server",
       "type": "php",
       "request": "launch",
-      "runtimeArgs": ["-dxdebug.mode=debug", "-dxdebug.start_with_request=yes", "-S", "localhost:0"],
+      "runtimeArgs": [
+        "-dxdebug.mode=debug",
+        "-dxdebug.start_with_request=yes",
+        "-dxdebug.client_port=${port}",
+        "-S",
+        "localhost:0"
+      ],
       "program": "",
       "cwd": "${workspaceRoot}",
-      "port": 9003,
+      "port": 0,
       "serverReadyAction": {
         "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
         "uriFormat": "http://localhost:%s",

tsconfig.json

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