How to Set Up and Use Xdebug in Magento 2 for Smarter PHP Debugging

Debugging Magento 2 can be challenging — it’s a massive framework with layered architecture, dependency injections, and countless class calls.

If you’re still using var_dump(), print_r(), or die() to track issues, it’s time to upgrade your debugging skills with Xdebug.

Xdebug is a PHP extension that gives you step debugging, variable inspection, profiling, and trace logging — all from within your IDE like VS Code.

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.

What Is Xdebug?

Xdebug is a PHP extension that enhances PHP’s debugging capabilities. It helps you trace the exact execution path, view call stacks, and inspect variables in real time.

Key Benefits of Xdebug:

• Step through your Magento code line-by-line.
• Set breakpoints and watch variables.
• Identify performance bottlenecks using profiling.
• Debug web requests and CLI commands with ease.

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.4-fpm then run this command:

sudo apt-get install php8.4-xdebug

The command installs the Xdebug extension for PHP 8.4. You can adjust the version number, for example, to use php8.x-xdebug for PHP 8.x

/etc/php/8.4/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.4-fpm restart

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

php --version

above command will output something like this:

PHP 8.4.13 (cli) (built: Oct  1 2025 20:33:51) (NTS)
Copyright (c) The PHP Group
Built by Debian
Zend Engine v4.4.13, Copyright (c) Zend Technologies
    with Zend OPcache v8.4.13, Copyright (c), by Zend Technologies
    with Xdebug v3.4.5, Copyright (c) 2002-2025, by Derick Rethans

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

Xdebug offers multiple configuration options that can be managed through the xdebug.ini file. After making changes, restart PHP-FPM and Apache for them to apply.

Once Xdebug is active, configure your IDE (like VS Code) to start debugging Magento code easily. Let’s check the key settings to include in the xdebug.ini file.

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

zend_extension = xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.idekey = VSCODE
xdebug.log = /var/log/xdebug.log

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

Setting	Description
xdebug.mode	Enables the debugging feature
xdebug.start_with_request	Starts debugging automatically with each request
xdebug.client_host	The IP address where your IDE runs
xdebug.client_port	Port used by Xdebug (default: 9003)
xdebug.idekey	Key used to identify the IDE
xdebug.log	Optional log file to track Xdebug activity

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,

When you hover near the line number, a red dot appears — click it to add a breakpoint. Then, select “Listen for Xdebug”, click the play button, and reload the page in your browser.

The editor will automatically return to the active breakpoint for debugging.

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

I hope this guide inspires other developers to integrate Xdebug into their daily development workflow to enhance debugging efficiency and streamline the coding process.

In my next blog, I’ll cover profiling with Xdebug and KCachegrind for deeper performance analysis.

Thanks 🙂