Setup XDebug with Visual Studio Code

Why use a debugging tool?

If you are a PHP based web application developer, you must be knowing the frustrations of debugging using echo-exit, print_r-exit, console.log() and other debugging tricks which most of us do in our daily work. For such debugging, tools like Xdebug really help us in smoothing out the operations, and also saving us a lot of time, thus increasing our efficiency.

What is Xdebug?

Xdebug is a debugging tool specifically made for PHP. You can learn more about Xdebug on their official website:

Why VS Code?

VS Code is just a choice. You can connect Xdebug with any favourite editor of your choice such as Phpstorm, Netbeans, Atom and Eclipse.


For proceeding with the setup in this article, you need to have the following requirements and prerequisites:

Setting up Xdebug with PHP


You can install using the following command

sudo apt-install php-xdebug

Setup with your PHP

Once it is installed, we need to configure it with our local PHP. First check your PHP version using the following command

php -v

Next, open your Xdebug configuration file which should be on the following path:


For me, as I was using PHP 7.4, it was at /etc/php/7.4/cli/conf.d/20-xdebug.ini

For editing the config file, I used gedit with sudo as follows so that there are no permission issues:

sudo gedit /etc/php/7.x/cli/conf.d/20-xdebug.ini

Once you open the configuration file, add the following:

# xdebug v2.x
xdebug.remote_connect_back=1 # Not safe for production servers
# xdebug v3.x
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_port = 9000

Save the file and close

Now make a local info.php file in your localhost. If you are using Apache localhost, then it should be in /var/www/html/info.php

Add the following code and save the file.


Now open the info file in your browser (for example: localhost/info.php)

You should be able to see a page like this

On this page, search for “Loaded Configuration File”. This is your PHP configuration file

Open this file in an editor and add the following

xdebug.remote_connect_back=1 # Not safe for production servers
xdebug.remote_mode=req xdebug.remote_autostart=true
xdebug.remote_autostart = 1

Now restart your local server. On my server it is apache so I restarted it using the following command

sudo service apache2 restart

Now reload your info.php in your browser and search for Xdebug. You should be able to see Xdebug installed

This confirms that Xdebug is installed in your local PHP

Download Xdebug extension for Chrome/Firefox

Before we proceed to connect Xdebug with VS Code, we need to download its extension for Chrome/Firefox

Chrome Xdebug extension

Firefox Xdebug extension

Once the extension is installed in your browser, we need to set the IDE key for our extension. For Chrome users, go to Settings -> Extensions -> Xdebug Helper -> Click on Details -> Click on Extension Options. You should be able to see a page like below

Here, you need to set the IDE key. For VS Code it is VSCODE. For atom, it is xdebug-atom as you can see in the image

That is all we need to do to setup Xdebug on our system.

Connect Xdebug to VS Code

Now we need to connect the installed Xdebug to our editor VS Code. Open VS Code and press Ctrl+Shift+X and type “PHP Debug”.

Select PHP Debug package by Felix Becker and install it.

If you have an older version of VS Code, you might see a Debug tab on the left like below

In the latest versions, they have renamed it to Run (Ctrl+Shift+D)…yeah so confusing.

Click on Run and you should be able to see a dropdown as below

Select “Add Configuration” and a launch.json file will open. Your launch.json file should have the following content

{// Use IntelliSense to learn about possible attributes.// Hover to view descriptions of existing attributes.// For more information, visit:"version": "0.2.0","configurations": [{"name": "Listen for XDebug","type": "php","request": "launch","port": 9000},{"type": "pwa-chrome","request": "launch","name": "Launch Chrome against localhost","url": "http://localhost:8080","webRoot": "${workspaceFolder}"}]}

In my case, the following configuration was missing, which I had to add manually. If it is already present, you don’t need to add or change anything.

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

Save this file and restart VS Code

Now click on Run again and in the dropdown 2 options should appear:

Time to test

Finally! After so much installation and configuration we can test Xdebug with our editor. For testing purpose, you can create a new PHP file and add the code below:

<?php$var1 = "hello";$var2 = "sufyan";$res = $var1." ".$var2;echo $res;exit;?>

You can name it as debugtest.php and open it in your broswer (localhost/debugtest.php). You should be able to see the output as “hello sufyan”

Now we are going to add a breakpoint on the line where we are concatenating the two strings

$res = $var1." ".$var2;

To add a breakpoint, hover on line number on the left and you should be able to see red dots. On clicking on that red dot, that line should be marked with a red dot. We are going to do this for the line above. You should be able to see something like below.

Ohh and if you don’t know what a breakpoint is, it is just an intentional stopping in our program execution. As we have added a breakpoint on that line above, the program execution should stop at that line and give us many details happened till the execution of that line. No need to worry if you don’t understand it now. We are going to see a working example below.

Once you add a breakpoint on the line specified above, you need to click on Run and in the dropdown select “Listen for XDebug” and then click on Start Debugging button on the left of the dropdown (looks like a play button)

Now our program is ready for debugging. Run this script on you browser and VS Code should open at that breakpoint. Isn’t this cool?!

Now if you see in VS Code there are 4 tabs on the left:

If you expand Variables, you will see 3 variables of our script. You will see $res as uninitialised because our breakpoint line is not executed yet. Now we have total control on the program execution, line by line. You can execute one line by clicking on Step Over (or press F10). Step Over button is present on a menu above

Once you click on it, the current line will be executed. Now, as current line is executed, we will see the value of the $res variable is changed to “hello sufyan”

This is a simplest example of debugging we can test.

Duh! Who uses such simple script in real life?

Yes, and Xdebug is not made for such simple scripts. In real life, we use PHP based MVC frameworks like Laravel, Symfony, Magento and others. Xdebug makes debugging a lot easier for such frameworks as we don’t have to echo-exit or console log everything.

I will try to cover an example in Magento 2 in another article

To wrap it up

Debugging PHP based web applications is tiresome and very time consuming if you check the code manually line-by-line. To handle this, debugging tools like Xdebug are made with which your debugging time is reduced 10x and thus improve you efficiency in day-to-day work life.

And yeah, this is a use case for PHP, you can do the same for any other language such as Python, JS based platforms such as Node JS, etc. Although their setup and configuration will be different, it will be on the similar lines.

If you have any questions, please ask them in the comments below.

Thank you. Happy coding!

Loving my fate