Setup XDebug with Visual Studio Code

Why use a debugging tool?

What is Xdebug?

Why VS Code?

Prerequisites:

  1. Linux OS
  2. Apache or any other server installed on localhost
  3. Visual Studio code installed
  4. PHP installed

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:

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

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_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1 # Not safe for production servers
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=true
# 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.

<?php
phpinfo();
?>

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]
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1 # Not safe for production servers
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
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

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: https://go.microsoft.com/fwlink/?linkid=830387"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:

  1. Listen for XDebug
  2. Launch Chrome against localhost

Time to test

<?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:

  1. Variables
  2. Watch
  3. Call Stack
  4. Breakpoints

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

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store