Enable Xdebug in VSCode for PHP

Xdebug is a PHP extension that provides debugging and profiling capabilities. This article shows how you can enable and use Xdebug in the VSCode code editor.

Install Xdebug

Xdebug installation instruction is present here: https://xdebug.org/docs/install

You can also follow these steps to get detailed instructions on installing Xdebug based on your system (Mac, Linux, Windows):

1. Create a file named phpinfo.php
2. Write the following in it and save the file:

   
   <?php phpinfo(); ?>
   

3. Open the file link in a browser, like http://localhost/phpinfo.php. You would see the detailed PHP Configuration Info installed on your machine.
4. Copy all the contents of the page
5. Alternatively, you can also save the phpinfo content in a file via command line

   
   PHP -i > phpinfo.txt
   

   And, then open the phpinfo.txt file and copy its content.

6. Go to the Xdebug Installation Wizard Page: https://xdebug.org/wizard . This page helps you find which file to download, and how to configure PHP to get Xdebug running.
7. Paste the phpinfo content in the input box present in the Xdebug installation wizard page
8. Click on the “Analyse my phpinfo() output” button
9. It will then give you detailed instructions on installing Xdebug based on your system (Mac, Linux, Windows)

Configure PHP to use Xdebug

Open the phpinfo.php page you created above and check the path to the loaded configuration file: php.ini or xdebug.ini file for Xdebug.

Edit the php.ini or xdebug.ini file (whichever is the configuration file for your Xdebug), and add the following to the file:

[XDebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1

Install PHP Debug Extension on VSCode

Open VSCode editor.

Install the extension “PHP Debug” by Felix Becker.

Create launch.json file

1. Open your project in VSCode.
2. In the left sidebar where you have the folder, extension, search, etc. icons, now you will also see the “Debugger” icon.
3. Click on the “Debugger” icon.
4. Click on a link to “create a launch.json file“



5. It will show a popup to select the environment. Select “PHP” as the environment.
6. This will create a file .vscode/launch.json with the required configuration settings auto-loaded.

This is a sample .vscode/launch.json file for a non-docker or local environment setup:

Note:
I am using Xdebug 2.
So, the port number in the launch.json file is set as 9000.
For Xdebug 3, the default port number is changed to 9003.

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000
    },
    {
      "name": "Launch currently open script",
      "type": "php",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",
      "port": 9000
    }
  ]
}

In the above launch.json file, there are two configuration settings:
– Listen for Xdebug
– Launch the currently open script

Listen for XDebug

• This setting will simply start listening on the specified port for XDebug. The default port for Xdebug 2 is 9000 and for Xdebug 3 it’s 9003.
• Every time you make a request with a browser to your web server 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.json file for docker setup

This is a sample .vscode/launch.json file for the docker environment setup:

Note:
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.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug on Docker",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/html/": "${workspaceFolder}"
            }
        }
    ]
}

The pathMappings in the above launch.json file indicates a mapping of server paths to local paths.

pathMappings: A list of server paths mapping to the local source paths on your machine.

Path mapping is used to make VS Code map the files on the server to the right files on your local machine.

If ${workspaceFolder} doesn’t work then you can try writing the absolute path to your project folder, like /Users/mukeshchapagain/Sites/your-project.

Start/Stop Debugging in VSCode

1. Open VSCode editor
2. Open a file. Typically, the index.php file.
3. Set a breakpoint in the file.
4. Click on the menu: Run > Start Debugging or Press F5 to start debugging
5. Browse your site, e.g. https://localhost/project/index.php
6. You should be able to see the variables section populated in the Debug section of your VSCode editor.
7. An icon set will appear in the code editor from where you can Continue (F5), Step Over (F10), Step Into (F11), Step Out (Shift+F11), Restart (Shift+CMD+F5), or Stop (Shift+F5) the debugger.

Step Into:

• In the debugging process, you reached a function call.
• You clicked on the “Step Into” button.
• The debugger will go inside that function and you can see how the function is executing line by line till it returns.
• After it returns, the debugger takes you back to the next line right after your initial function call.

Step Over:

• In the debugging process, you reached a function call.
• You clicked on the “Step Over” button.
• The debugger just executes it like a black box, returns the result, and goes to the next line.
• You cannot see how the function was executed.

Step Out:

• In the debugging process, you reached a function call.
• You clicked on the “Step Into” button.
• The debugger will go inside that function and you can see how the function is executing line by line till it returns.
• Now, if you don’t want to see the line-by-line execution of this function and want to return back early to the previous function, then you can click “Step Out”.
• The debugger will go back to the next line of your previous function call.

Hope this helps. Thanks.