Installing and Using Xdebug for Magento with PhpStorm

With layered architecture, plugin chains, and endless XML configs, debugging Magento can be extremely challenging. But that’s true only if you don’t know the right tricks.

Xdebug is a dynamic PHP extension that helps you step through your code, variable by variable, line by line. When you pair it with PhpStorm, you get the perfect debugging duo that helps you debug Magento like you’ve only dreamt of.

Today, we will talk you through the entire process of installing and configuring Xdebug for Magento with PhpStorm. If you follow the process carefully, there are no errors you can’t handle. Whether the issues are buried deep in a plugin, hiding in a controller, or lost in a CLI command, you can fix them without any guesswork.

What is Xdebug?

Xdebug is a popular and powerful profiling and debugging tool for PHP that helps analyze and debug even the most complex codebase with ease. With Xdebug by your side, you can easily understand what’s going on under the hood and fix every single issue.

When you deal with complex observers, call chains, and plugins, debugging can feel like a never-ending labyrinth. Xdebug simplifies the debugging process with in-depth insights and execution tracing.

Benefits of Using PhpStorm with Xdebug

When you pair PhpStorm with Xdebug, they seamlessly integrate to deliver a powerful debugging environment, offering features like inspecting variable states, stepping through codes, and real-time evaluation of expressions.

With PhpStorm, even the most arduous debugging process can turn into an enjoyable and efficient experience, which saves you time as you don’t feel like wrestling with Magento’s extensive framework.

How to Install and Use Xdebug for Magento with PhpStorm

We have explained the process of installing and using Xdebug in different stages, which will help you debug in the simplest way possible.

Prerequisites

Before jumping into the installation and configuration, make sure that the following are up and ready.

• PHP Installed: Double-check whether your PHP version is compatible with Xdebug.
• PhpStorm Installed: PhpStorm is the IDE (Integrated Development Environment) for a seamless Xdebug experience.
• Local Web Server: Make sure you have set up your local server on Nginx, Apache, or PHP built-in server.

Installing Xdebug

Before proceeding with the installation, check whether Xdebug has already been installed. Here’s how you can check:

Open your terminal and run:

php -v or php -m

You will see Xdebug listed there if it’s already installed.

Installation Options

• Using PECL:

pecl install xdebug

• OS-Specific Tools:

For macOS, you might use Homebrew:

brew install xdebug

• For Ubuntu

When using Ubuntu, Xdebug can be installed using the default package manager by running the following command:

sudo apt install php-xdebug

Once the installation is complete, you can typically locate the configuration file at /etc/php/<version>/mods-available/xdebug.ini. You need to make sure that the Xdebug settings are correct here (for example, zend_extension=xdebug.so). You can then use phpenmod xdebug to enable it and restart your web server (sudo systemctl restart apache2 or php-fpm) to ensure the changes are in effect. Run php -v or php -m and locate “Xdebug” in the output to confirm that the installation is successful.

For those who are using Magento Docker, certain Docker images come with pre-installed Xdebug. If that’s not the case, you may need to update your Dockerfile to add Xdebug.

Configuring Xdebug

Update the Correct php.ini

Most of the time, Magento setups use distinct PHP configurations for web server contexts and CLI. You need to make sure that you’re updating the correct php.ini file according to the debugging context.

• Web Server PHP.ini: Browser-based debugging.
• CLI PHP.ini: Magento CLI commands.

Sample Xdebug config for Web Requests

zend_extension=xdebug.so

xdebug.mode=debug

xdebug.start_with_request=trigger

xdebug.client_host=127.0.0.1

xdebug.client_port=9003

xdebug.log_level=0

For those using PHP-FPM, you may also add:

php_admin_value[xdebug.mode] = debug

php_admin_value[xdebug.start_with_request] = trigger

Sample Xdebug config for CLI

zend_extension=xdebug.so

xdebug.mode=debug

xdebug.start_with_request=yes

xdebug.client_host=127.0.0.1

xdebug.client_port=9003

xdebug.log_level=0

For Windows, replace xdebug.so with xdebug.dll (e.g., zend_extension=”C:\php\ext\xdebug.dll”).

For Docker setups, set xdebug.client_host=host.docker.internal (macOS/Windows) or the host IP (Linux). After making changes, restart your web server or PHP-FPM.

Note: Setting xdebug.client_host=127.0.0.1 is applicable for local debugging (IDE and PHP on the same machine). use the host’s IP (for example, host.docker.internal) or enable xdebug.discover_client_host=1 for Docker/VMs.

Since Magento CLI commands depend on the same debugging mechanisms, you have to ensure that your Xdebug configuration contains settings optimized for the Magento environment and they are consistent across CLI settings and web.

Verifying Xdebug Installation

Browser & CLI Checks

• For Web: Create a basic PHP file that includes the following command:

<?php phpinfo(); ?>

Open the file in your browser and locate the Xdebug section.

• Via CLI: Run the following command:

php -i | grep xdebug

If you see Xdebug in the output, you’re ready to roll.

Configuring PhpStorm

Now, set up your PHP interpreter, configure the debugger, and create the correct server configurations to ensure that PhpStorm works with Xdebug. Here are the things you need to make sure:

• PhpStorms properly recognizes Xdebug.
• You have correctly mapped your project paths.
• The IDE is able to receive incoming debug connections to make sure that none of the breakpoints is missed.

Following are the steps to configure PhpStorm.

1. Set Up PHP Interpreter: Navigate to File → Settings → PHP (or PhpStorm → Preferences on macOS). Add your PHP executable (e.g., /usr/bin/php or Docker path). Make sure Xdebug is located under extensions.
2. Configure Debugger: Go to File → Settings → PHP → Debug. Set the Xdebug port to 9003 (Xdebug 3). Enable “Can accept external connections.”
3. Set Up Server Mappings: Go to File → Settings → PHP → Servers. Add a server with:
   • Name: Your Magento site (e.g., magento.local).
   • Host: Your local domain.
   • Port: 80 or 443.
   • Debugger: Xdebug.
     Map your project root to the server’s document root.
4. Validate Debugger: Navigate to Run → Web Server Debug Validation. Put your server URL (for example, http://magento.local) and choose the PHP interpreter. Follow the suggestions to fix issues.

Debugging a Magento Request

Setting Breakpoints: Open PhpStorm and place breakpoints in your Magento code where you feel issues may exist. 

Initiate a Debug Session: Add the following to your Magento URL to start the debugging process:

?XDEBUG_SESSION_START=PHPSTORM

This commands Xdebug to start a debug session. You can leverage PhpStorm’s interface to step through the code – step over lines, step into functions, and check variable values while the request is processed by Magento.

Debugging Magento CLI Commands

Occasionally, the bugs surface only when you execute Magento CLI commands. Here’s what you can do in such scenarios:

• Place breakpoints right in your source code. For example, you can set breakpoints in CLI command classes or setup scripts.
• Execute the CLI command and allow the debugger to catch it, which can help you step through the entire process and detect the issue.

Troubleshooting

When you are trying to debug Magento, even the finest setups are not foolproof. Here are some common troubleshooting tips to ensure a seamless debugging process.

• Breakpoints Aren’t Working: Confirm whether you have updated the appropriate php.ini file and make sure that PhpStorm is accurately configured to listen on the correct port.
• Docker Issues: For those who are using Docker, make sure that the Xdebug settings are not overridden by your container configuration.
• Magento-Specific Tips: You may need to make some additional configuration tweaks to tackle Magento’s complexity. Make sure that Magento’s CLI behavior is not overriding your debugger.

Tips and Best Practices

• Disable Xdebug in Production: Do not enable Xdebug on live servers to prevent a negative impact on performance.
• Use Conditional Breakpoints: The conditional breakpoints work like a charm for complex plugin chains as they help terminate the execution if specific conditions are met.
• Log Stack Traces: Log stack traces when required by leveraging xdebug_print_function_stack().
• Leverage PhpStorm’s “Evaluate Expression”: With this, you can dynamically debug and inspect variables to get real-time insights into your code.
• Magento-Specific Insight: Xdebug is extremely efficient in tracing Magento’s dependency injection resolution, event dispatches, and plugin chains.

Conclusion

Xdebug is more than your regular debugging Joe; it’s a powerful tool for PHP and Magento development. Coupled with PhpStorm, it can totally revolutionize the way you track and fix bugs in your store. By turning guesswork into precise, calculated tasks, Xdebug helps you save countless hours of head-scratching and frustration. Just invest some time in the proper setup, and Xdebug, combined with PhpStorm, will help you fix issues on your Magento store in the fastest, finest, and most efficient way possible.