Xdebug for debugging the Magento2 application

Xdebug is a powerful tool to make php developer’s life much easier, it’s a PHP extension that developers must use only in the development phase, it’s not meant for production environments.

Xdebug helps developers to easily debug the code without doing anything with the code, so traditional developers use var_dump, print_r, die, and debug_print_backtrace like php methods to check issues in the code which is fine but not smart.

Applications like Magento2 have a highly complex structure, hundreds of files and methods are invoked when we load a page, debugging a small issue can take a lot of time, and keeping track of all the files where you have added debugging code is also hectic, many times it happens when developers left a var_dump in some code files and deploy it on a client live website which is not acceptable at all.

Xdebug is also used to generate profiling data which we can analyze in tools like kcachegrind to find out performance bottlenecks.

Let’s understand the different modes of Xdebug

• develop: enabling this mode will enhance the debugging functions of PHP like var_dump to show more information to the developer for a better understanding of the issue it will add pre-tags automatically, show stack trace, etc.
• coverage: This mode will help in better code coverage for php unit test cases
• debug: this will enable step debugging so that developer can trace each step of the request and can easily add breakpoints in the code to find the root cause of the issues
• gcstats: this will show statistics related to the PHP garbage collector
• profile: enabling this will generate cachegrind files which can be analyzed is kcachegrind in order to find performance issues
• trace: enabling this mode will result in generating the whole request trace in the log where cachegrind files are generated with trace.*.txt name which can be in 3 formats human-readable format, machine format, and HTML format this can be very useful to understand the whole application flow, but warning it will generate a huge file(in GB) in application like Magento2
• off: this will turn off Xdebug

Installation

Xdebug can be installed like any other PHP extension, if you are installing it on Ubuntu with Apache and php8.1-fpm then run this command:

sudo apt-get install php8.1-xdebug

the above command will install the Xdebug extension for PHP 8.1, according to the PHP version you can change the version number like this php8.2-xdebug, after successfully executing the above command, you can find its ini file on this path:

/etc/php/8.1/apache2/conf.d/20-xdebug.ini

Or you can find its location simply by running this command :

php -i | grep xdebug

or by outputting php_info() function on the webpage.

In the ini file make sure this line is there and uncommented:

zend_extension=xdebug.so

after that you need to restart the php fpm and apache using the below commands:

sudo service apach2 restart

sudo service php8.1-fpm restart

now run this command to confirm Xdebug is installed and working:

php --version

above command will output something like this:

PHP 8.1.17 (cli) (built: Mar 16 2023 14:38:17) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.17, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.17, Copyright (c), by Zend Technologies
    with Xdebug v3.2.0, Copyright (c) 2002-2022, by Derick Rethans

Now let’s dive into how to configure Xdebug to debug code in vs code editor

Xdebug comes with lots of configuration options, we can add those configurations in the xdebug.ini file and after that, we need to restart php fpm and apache to see those changes working and we also need to configure vs code so that we can directly debug the code in the editor, lets first see the ini file configurations:

you need to add the below settings to your xdebug.ini file:

xdebug.log=/Path_In_Your_System/xdebug.log
xdebug.mode=debug
xdebug.idekey=VSCODE
xdebug.client_port=9003
xdebug.start_with_request=yes

xdebug.log is the setting to set a log file path, where Xdebug will show its status, errors, and connections this can be any location on your system

xdebug.mode is to set mode, in the above setting I have only set debug, you can also set other modes as well like this :

xdebug.mode=debug,profile,trace

• xdebug.idekey is the editor code for vs-code it is VSCODE
• xdebug.client_port is the port where Xdebug will run by default it is 9003
• xdebug.start_with_request This setting explains when Xdebug will start debugging, ‘yes’ means when an HTTP request is initiated then it will start working.

we can also set other options as well, like:

xdebug.start_with_request=trigger

if this option is set then Xdebug will only work if there is an XDEBUG_TRIGGER option set in either GET, POST, or Cookie in the request or we can also add this :

xdebug.start_with_request=trigger
xdebug.trigger_value=MyCustomValue

trigger_value setting will ensure that Xdebug will only work in the XDEBUG_TRIGGER option value is set to MyCustomValue.

Now let’s understand how to configure vs code to start using xdebug

Open vs code editor and press:

CTRL+SHIFT+X

to open the extensions tab now search for “php debug” This will show the PHP Debug extension install the extension by clicking on the install button:

Now on the top menu in vs code open the ‘Run’ menu and click on “add configuration” It will open the launch.json file with three configuration options:

Listen For Xdebug

we will be using this configuration, it starts debugging as soon as a request starts running and an Xdebug connection is created

Launch Currently Open Script

this is used to debug currently open scripts as a standalone or console program

Launch Built-in web server

this will launch a web server and create an Xdebug connection

Now in vs code open the “Run and Debug” tab by running :

CTRL+SHIFT+D

Now on the left top, you can see “Run And Debug” where there will be a green play button and dropdown of launch.json file configurations to choose, from before opening a code file and adding some breakpoints by clicking before the line number,

on hovering there you can see a red dot appear, just click on the line number to add the breakpoints, now choose “Listen For Xdebug” click on the play button, and load the page from the browser and it will take you back to the editor with active breakpoint like below:

After coming back to the breakpoints you will also see a tool on top of the code like below:

You can drag that tool horizontally anywhere on the editor, let’s see all the options there:

1. Pause: this button is to pause the step debugging if you are doing something else and later again start it to start the step debugging.
2. Step Over: this will move the step directly to the next breakpoint
3. Step into: this will move the step to the next function call
4. Restart: this will restart the debugging from the first breakpoint
5. Stop: this will stop the debugging until you start a new one.

On the left section of the editor, you can also see some sections like variables, watch, call stack, and breakpoints like this:

• Variables will show all the variables accessible on that page
• watch section is where you can add variables, and functions to watch throughout the whole execution, you can add them by simply selecting them into the code and right click on them then “click add to watch”
• Call Stack will show the backtrace of calls of functions for each step
• Breakpoints will show all the breakpoints that you have added

Hope this will encourage and help other developers to adopt xdebug into their daily development habits to optimize the development process, in my next blog I will explain profiling using Xdebug and kcahegrind.

Thanks 🙂