Xdebug – configuration, PHPStorm, debugging Magento plugins

Everyone starts with var_dump() and die(). But after a few years working with PHP and Magento 2, those methods start to hurt – especially when debugging a complex order flow with dozens of plugins. I show how to set up Xdebug and why it is worth doing once, properly.

The problem with var_dump in production environments

On large objects (e.g. Magento\Sales\Model\Order) var_dump() dumps tens of thousands of lines that tell you practically nothing. Xdebug solves both problems.

Installing Xdebug 2.x on PHP 7.2

# Check PHP version and architecture
php -v
php -i | grep "PHP Extension Build"

# Install via pecl
pecl install xdebug

# Or via apt (Ubuntu/Debian)
sudo apt-get install php7.2-xdebug

After installation add to php.ini:

[xdebug]
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_autostart=0
xdebug.idekey=PHPSTORM
xdebug.max_nesting_level=512

Note for Magento: set max_nesting_level to at least 512. Magento has deeply nested DI calls and at a lower limit Xdebug will stop the script too early.

PHPStorm configuration

In PHPStorm go to Settings > PHP > Debug and make sure the port is 9000 (Xdebug 2.x) or 9003 (Xdebug 3.x). Then:

1. Click the phone icon (Start Listening for PHP Debug Connections)
2. Set a breakpoint in the code (click on a line number)
3. Call the URL with ?XDEBUG_SESSION_START=PHPSTORM or use the Xdebug Helper browser extension

Practical example – debugging a Magento plugin

<?php

namespace Vendor\Module\Plugin;

use Magento\Catalog\Model\Product;

class PricePlugin
{
    public function afterGetPrice(Product $subject, float $result): float
    {
        // Set a breakpoint here - PHPStorm shows $subject, $result and the full call stack
        $modifiedPrice = $result * 0.9;

        return $modifiedPrice;
    }
}

Summary

Setting up Xdebug takes 15-20 minutes and pays off after the first debugging session on a complex problem. If you work with Magento 2, where a single request can pass through a dozen plugins and interceptors – this is an absolute must-have.