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

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 🙂