Debug Overview

PHP Xdebug with VSCode Overview

Debugging of PHP code in VS Code allows for inspecting a PHP program, inspecting actual variables, stack traces, exceptions, breaking and stepping through the code, debugging PHPUnit tests, and more.

Requirements

In order to debug a PHP program, you need PHP (either installed locally or on your server) together with Xdebug extension.

PHP >= 5.6
Xdebug extension. Follow the steps on Xdebug.org Install.

Local PHP Installation

In case there are more PHP installations on the system, see choosing PHP Version and select the right one.

To verify your PHP and Xdebug are installed correctly:

Open a .php file in VS Code
Open the OUTPUT view, tab PHP.

PHP info

If PHP with Xdebug is installed correctly, you will see

Found PHP, version x.y.z, Xdebug: x.y.z.

`php.ini` Configuration

Xdebug needs to be set in php.ini file that corresponds to your PHP installation.

On Windows it is located next to your php.exe.
On Linux/Mac, there is usually a separate xdebug.ini file (usually something like /etc/php/8.0/cli/xdebug.ini).

Edit the .ini file, and ensure there are the following directives (Note, the directives are different for Xdebug versions 2 and 3):

; Xdebug 3
zend_extension = "<path to the xdebug library>" ; "...\xdebug.dll" or ".../xdebug.so"
xdebug.mode = debug
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.start_with_request = trigger

; Xdebug 2
zend_extension = "<path to the xdebug library>" ; "...\xdebug.dll" or ".../xdebug.so"
xdebug.remote_enable = 1
xdebug.remote_handler = dbgp
xdebug.remote_host = 127.0.0.1
xdebug.remote_port = 9000
xdebug.remote_mode = req

Server PHP Installation

This applies to the situation when PHP is not running on your local system but it's on a Cloud, Web Host, Docker, Xampp, etc.

In case php itself is not running on your local system, consult the installation of PHP+Xdebug with the specific server host.

You can then take advantage of DBGP Proxy to allow multiple users to debug the same site safely.

Launching Debug in VSCode

Launch debugging in Visual Studio Code to either run the program and debug, or to listen for incoming Xdebug connections and debug. PHP debugging can be initiated in several ways, with or without VS Code Workspace, with or without the configured launch.json.

With `launch.json`

The file .vscode/launch.json is a configuration file within your VS Code Folder or Workspace.

Open Folder or Open Workspace in VS Code. This allows for specifying more detailed debug launch configurations.
Navigate to Run and Debug view, and click create a launch.json or the configuration gear:
See launch.json for the initialization and description of the PHP launch profiles.

No `launch.json`, Just Debug

Debugging can be started without any configuration. This is recommended if you just need to attach to an existing Web Server (with Xdebug configured) or to quickly run and debug a PHP script.

Open a .php file in VS Code (File / Open File).
Press F5 or Open Command Palette (F1) and choose one of the following:

Listen for Xdebug starts debugging and waits for an incoming Xdebug connection.
Launch current script in console runs and debugs the currently opened PHP document as a console PHP program.
Launch built-in server starts PHP development server within your opened folder, checks for the debugging capabilities, and starts listening for the Xdebug connections.

Features

The debugging features are the following:

Stepping by line, step in, step out.
Placing breakpoints, conditional breakpoints, break on hit count.
Logging breakpoint hit into 'Debug console'.
Breaking on exceptions, warnings, and errors.
Specifying non-user files (exceptions won't break debugging, stepping through).
Watch tool tips.
Listing locals and superglobals.
Editing variable or property value, handling long string values efficiently.
Long arrays watch efficiently.
Debug watch expands objects and arrays.
Evaluating code in 'Debug console'.
Debug launch profiles.
Built-in web development server.
Debugging of 'PHP Unit' test cases.

Debug Adornments

When stepping through the code, the editor will display values of variables and expressions corresponding to the current statement. Values are also shown for the enclosing scopes such as loop control variables, switch expression, and function parameters.

This feature can be enabled or disabled using VS Code Setting "debug.inlineValues".

PHP debug inlines

Start Debug and Stop on Entry

Open command palette and run Start Debugging and Stop on Entry (aka Step Into). The command launches debugging and breaks on the first statement.

Troubleshooting

These are steps that should help to diagnose and solve common problems with debugging PHP:

Running the following command should display no warnings, and an Xdebug notice:

php --version

PHP 8.0.3 (cli) Copyright (c) The PHP Group
Zend Engine v4.0.3, Copyright (c) Zend Technologies
  with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick Rethans

The port number specified in Xdebug .ini configuration should be 9000 or 9003, or it should match the "port" specified in the Launch Profiles.
Firewall must be properly set up to allow communication through the Xdebug port.
Append the following query parameter when opening the debugged PHP Web Site:
```
?XDEBUG_SESSION_START=1
```
For example: http://localhost/?XDEBUG_SESSION_START=1
In case the VS Code is behind a proxy, see https://code.visualstudio.com/docs/setup/network for additional settings.