Home

Awesome

PHP Debug Adapter for Visual Studio Code

vs marketplace downloads rating build status codecov code style: prettier semantic-release

Demo GIF

Sponsor PHP Debug Adapter for Visual Studio Code

If you find this extension useful, if it helps you solve your problems and if you appreciate the support given here, consider sponsoring our work.

Installation

Install the extension: Press F1, type ext install php-debug.

This extension is a debug adapter between VS Code and Xdebug by Derick Rethans. Xdebug is a PHP extension (a .so file on Linux and a .dll on Windows) that needs to be installed on your server.

  1. Install Xdebug I highly recommend you make a simple test.php file, put a phpinfo(); statement in there, then copy the output and paste it into the Xdebug installation wizard. It will analyze it and give you tailored installation instructions for your environment. In short:

    • On Windows: Download the appropriate precompiled DLL for your PHP version, architecture (64/32 Bit), thread safety (TS/NTS) and Visual Studio compiler version and place it in your PHP extension folder.
    • On Linux: Either download the source code as a tarball or clone it with git, then compile it. Or see if your distribution already offers prebuilt packages.
  2. Configure PHP to use Xdebug by adding zend_extension=path/to/xdebug to your php.ini. The path of your php.ini is shown in your phpinfo() output under "Loaded Configuration File".

  3. Enable remote debugging in your php.ini:

    For Xdebug v3.x.x:

    xdebug.mode = debug
    xdebug.start_with_request = yes
    

    For Xdebug v2.x.x:

    xdebug.remote_enable = 1
    xdebug.remote_autostart = 1
    xdebug.remote_port = 9000
    

    There are other ways to tell Xdebug to connect to a remote debugger, like cookies, query parameters or browser extensions. I recommend remote_autostart (Xdebug v2)/start_with_request (Xdebug v3) because it "just works". There are also a variety of other options, like the port, please see the Xdebug documentation on remote debugging for more information. Please note that the default Xdebug port changed between Xdebug v2 to v3 from 9000 to 9003.

  4. If you are doing web development, don't forget to restart your webserver to reload the settings.

  5. Verify your installation by checking your phpinfo() output for an Xdebug section.

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 three configurations:

There are also configurations for Xdebug v2 (Legacy) installations.

More general information on debugging with VS Code can be found on https://code.visualstudio.com/docs/editor/debugging.

Note: You can even debug a script without launch.json. If no folder is open, and the VS Code status bar is purple, pressing F5 will start the open script with Xdebug3 specific parameters. If the php executable is not in path, you can provide it with the setting php.debug.executablePath. For debugging to work, Xdebug must still be correctly installed.

Supported launch.json settings:

Options specific to CLI debugging:

Features

Remote Host Debugging

To debug a running application on a remote host, you need to tell Xdebug to connect to a different IP than localhost. This can either be done by setting xdebug.client_host to your IP or by setting xdebug.discover_client_host = 1 to make Xdebug always connect back to the machine who did the web request. The latter is the only setting that supports multiple users debugging the same server and "just works" for web projects. Again, please see the Xdebug documentation on the subject for more information.

To make VS Code map the files on the server to the right files on your local machine, you have to set the pathMappings settings in your launch.json. Example:

// server -> local
"pathMappings": {
  "/var/www/html": "${workspaceFolder}/www",
  "/app": "${workspaceFolder}/app"
}

Please also note that setting any of the CLI debugging options will not work with remote host debugging, because the script is always launched locally. If you want to debug a CLI script on a remote host, you need to launch it manually from the command line.

Proxy support

The debugger can register itself to a DBGp proxy with a IDE Key. The proxy will then forward to the IDE only those DBGp sessions that have this specified IDE key. This is helpful in a multiuser environment where developers cannot use the same DBGp port at the same time. Careful setup is needed that requests to the web server contain the matching IDE key.

The official implementation of the dbgpProxy.

A Xdebug helper browser extension is also recommended. There the request side IDE key can be easily configured.

Troubleshooting

Contributing

To hack on this adapter, clone the repository and open it in VS Code. You need NodeJS with NPM installed and in your PATH. Also a recent PHP and Xdebug should be installed and in your PATH.

  1. Install NPM packages by either running npm install on command line in the project directory or selecting Terminal / Run Task... / npm / npm: install in VS Code menu.
  2. Run the build/watch process either by running npm run watch on command line in the project directory or selecting Terminal / Run Build Task... in VS Code menu.
  3. Start the debug adapter by opening the Run and Debug side bar, selecting Debug adapter configuration and clicking on the green Run arrow (or hitting F5). The compiled adapter will be running in "server mode" and listening on TCP port 4711.
  4. Run a separate instance of VS Code, called "Extension Development Host" by running code testproject --extensionDevelopmentPath=. on command line in the project directory or selecting the Launch Extension Run and Debug configuration and pressing the green Run arrow. Another shortcut is to run npm run start. You can also run an Insiders build of VS Code for testing newer features.
  5. In the "Extension Development Host" instance open .vscode/launch.json and uncomment the debugServer configuration line. Run your PHP debug session by selecting the desired configuration and hitting F5. Now you can debug the testproject like specified above and set breakpoints inside your first VS Code instance to step through the adapter code.

More on testing extensions can be found on https://code.visualstudio.com/api/working-with-extensions/testing-extension.

Tests are written with Mocha and can be run with npm test or from Terminal / Run Task... / npm: test. When you submit a PR the tests will be run in CI on Linux, macOS and Windows against multiple PHP and Xdebug versions.

Before submitting a PR also run npm run lint or Terminal / Run Tasks... / npm: lint.