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: https://xdebug.org/
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.
Prerequisites:
For proceeding with the setup in this article, you need to have the following requirements and prerequisites:
- Linux OS
- Apache or any other server installed on localhost
- Visual Studio code installed
- PHP installed
Setting up Xdebug with PHP
Installation
You can install using the following command
sudo apt-install php-xdebugSetup 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 -vNext, open your Xdebug configuration file which should be on the following path:
/etc/php/7.x/cli/conf.d/20-xdebug.iniFor 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.iniOnce 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 = 1Now restart your local server. On my server it is apache so I restarted it using the following command
sudo service apache2 restartNow 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
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: 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:
- Listen for XDebug
- Launch Chrome against localhost
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:
- Variables
- Watch
- Call Stack
- 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!
