feat: Launch integrated dev webserver without router-script (program) (#389)

* Allow starting PHP without providing program (for built-in web server)

* Add initial debug configuration for built-in web server.

* Initial and configuration snippets.

* Fixed missing Promise return type.

* Changelog.

* Readme.

Author: tonischranz

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- Option to start PHP built-in web server without router script.
+
 ## [1.15.1]
 
 ### Changed

README.md

@@ -52,12 +52,16 @@ This extension is a debug adapter between VS Code and [Xdebug](https://xdebug.or
 
 ### VS Code Configuration
 
-In your project, go to the debugger and hit the little gear icon and choose _PHP_. A new launch configuration will be created for you with two configurations:
+In your project, go to the debugger and hit the little gear icon and choose _PHP_. A new launch configuration will be created for you with three configurations:
 
 - **Listen for Xdebug**
-  This setting will simply start listening on the specified port (by default 9000) for Xdebug. If you configured Xdebug like recommended above, everytime you make a request with a browser to your webserver or launch a CLI script Xdebug will connect and you can stop on breakpoints, exceptions etc.
+  This setting will simply start listening on the specified port (by default 9000) for Xdebug. If you configured Xdebug like recommended above, every time you make a request with a browser to your webserver or launch a CLI script Xdebug will connect and you can stop on breakpoints, exceptions etc.
 - **Launch currently open script**
   This setting is an example of CLI debugging. It will launch the currently opened script as a CLI, show all stdout/stderr output in the debug console and end the debug session once the script exits.
+- **Launch Built-in web server**
+  This configuration starts the PHP built-in web server on a random port and opens the browser with the `serverReadyAction` directive. The port is random (localhost:0) but can be changed to a desired fixed port (ex: localhost:8080). If a router script is needed, add it with `program` directive. Additional PHP/Xdebug directives trigger debugging on every page load.
+
+More general information on debugging with VS Code can be found on https://code.visualstudio.com/docs/editor/debugging.
 
 #### Supported launch.json settings:
 

package.json

@@ -146,7 +146,9 @@
     "debuggers": [
       {
         "type": "php",
-        "languages": ["php"],
+        "languages": [
+          "php"
+        ],
         "label": "PHP",
         "program": "./out/phpDebug.js",
         "runtime": "node",
@@ -278,6 +280,25 @@
             "program": "${file}",
             "cwd": "${fileDirname}",
             "port": 9000
+          },
+          {
+            "name": "Launch Built-in web server",
+            "type": "php",
+            "request": "launch",
+            "runtimeArgs": [
+              "-dxdebug.mode=debug",
+              "-dxdebug.start_with_request=yes",
+              "-S",
+              "localhost:0"
+            ],
+            "program": "",
+            "cwd": "${workspaceRoot}",
+            "port": 9000,
+            "serverReadyAction": {
+              "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
+              "uriFormat": "http://localhost:%s",
+              "action": "openExternally"
+            }
           }
         ],
         "configurationSnippets": [
@@ -302,9 +323,32 @@
               "cwd": "^\"${2:\\${fileDirname\\}}\"",
               "port": 9000
             }
+          },
+          {
+            "label": "PHP: Launch Built-in web server",
+            "description": "Start built-in PHP web server and open browser on debug start",
+            "body": {
+              "name": "Launch Built-in web server",
+              "type": "php",
+              "request": "launch",
+              "runtimeArgs": [
+                "-dxdebug.mode=debug",
+                "-dxdebug.start_with_request=yes",
+                "-S",
+                "localhost:${1:0}"
+              ],
+              "program": "",
+              "cwd": "^\"${2:\\${workspaceRoot\\}}\"",
+              "port": 9000,
+              "serverReadyAction": {
+                "pattern": "Development Server \\\\(http://localhost:([0-9]+)\\\\) started",
+                "uriFormat": "http://localhost:%s",
+                "action": "openExternally"
+              }
+            }
           }
         ]
       }
     ]
   }
-}
+}

src/phpDebug.ts

@@ -212,19 +212,22 @@ class PhpDebugSession extends vscode.DebugSession {
         /** launches the script as CLI */
         const launchScript = async () => {
             // check if program exists
-            await new Promise<void>((resolve, reject) =>
-                fs.access(args.program!, fs.constants.F_OK, err => (err ? reject(err) : resolve()))
-            )
+            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 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
             // launch in CLI mode
             if (args.externalConsole) {
                 const script = await Terminal.launchInTerminal(
                     cwd,
-                    [runtimeExecutable, ...runtimeArgs, args.program!, ...programArgs],
+                    [runtimeExecutable, ...runtimeArgs, ...program, ...programArgs],
                     env
                 )
                 if (script) {
@@ -234,7 +237,7 @@ class PhpDebugSession extends vscode.DebugSession {
                     })
                 }
             } else {
-                const script = childProcess.spawn(runtimeExecutable, [...runtimeArgs, args.program!, ...programArgs], {
+                const script = childProcess.spawn(runtimeExecutable, [...runtimeArgs, ...program, ...programArgs], {
                     cwd,
                     env,
                 })
@@ -341,7 +344,7 @@ class PhpDebugSession extends vscode.DebugSession {
             if (!args.noDebug) {
                 await createServer()
             }
-            if (args.program) {
+            if (args.program || args.runtimeArgs) {
                 await launchScript()
             }
         } catch (error) {

testproject/.vscode/launch.json

@@ -11,12 +11,27 @@
     },
     {
       //"debugServer": 4711, // Uncomment for debugging the adapter
-      "name": "Launch",
-      "request": "launch",
+      "name": "Launch currently open script",
       "type": "php",
+      "request": "launch",
       "program": "${file}",
+      "cwd": "${fileDirname}",
+      "port": 9000
+    },
+    {
+      //"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"],
+      "program": "",
       "cwd": "${workspaceRoot}",
-      "externalConsole": false
+      "port": 9000,
+      "serverReadyAction": {
+        "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
+        "uriFormat": "http://localhost:%s",
+        "action": "openExternally"
+      }
     }
   ]
 }