Launch Profiles

Launch profiles define the way Visual Studio Code Debugger executes the project. The profiles can pass parameters to the debugger to modify its function.

launch.json

Visual Studio Code stores debugging configuration in a launch.json file located in a .vscode folder in a workspace (project root folder) or in user or workspace settings. The file can contain multiple profiles that can be selected before starting the debugger in the Debug pane in VS Code.

Launch profile selection

Web Application

The following profile starts the PHP built-in web server. The server is started only if the runtimeArgs contains the parameter -S that defines the location and port of the server.

Sample configuration:

{
    "name": "Launch Built-in server",
    "type": "php",
    "request": "launch",
    "runtimeArgs": [
        "-S",
        "localhost:8888",
        "-t",
        "\\remotepc\Shared\Test"
    ],
    "pathMappings": {
        "\\remotepc\Shared\Test\": "${workspaceRoot}\src",
        "\\test": "C:\Users\usr\Documents\VSCode\src\"
    },
    "port": 9000
}

Console Application

This profile runs the PHP project as a console application, inside the VS Code's Debug Console. By default it starts a file currently opened in the editor.

{
    "name": "Launch current script in Console",
    "type": "php",
    "request": "launch",
    "program": "${file}",
    "cwd": "${fileDirname}",
    "externalConsole": false,
    "port": 9000
}

Useful parameters that can be changed:

  • program: Specifies a file absolute or relative to workspace's directory. Value ${file} means the file currently opened in the editor.
  • externalConsole: true to run the program in a separate command line window. Default is false to output the program in the VS Code's Debug Console.
  • port: is the Xdebug port number. This value has to match setting in php.ini. Defaults to 9000.

Remote Application (Attach)

The following basic profile informs the debugger that it should try to connect to an already running Xdebug server. PHP Tools won't start any server, because there is no program or runtimeArgs parameter, like in the previous profiles.

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9000
}

Debug Current Script

Whenever there is no launch.json file present, PHP Tools' debugger launches the current PHP script in the VS Code's Debug Console.