Xdebug – konfiguracja, PHPStorm, debugowanie pluginów Magento

Każdy zaczyna od var_dump() i die(). Ale po kilku latach pracy z PHP i Magento 2, te metody zaczynają boleć – szczególnie gdy debugujesz złożony proces zamówienia z dziesiątkami pluginów. W tym wpisie pokazuję, jak ustawić Xdebug i dlaczego warto to zrobić raz, a dobrze.

Problem z var_dump w środowiskach produkcyjnych

Poza oczywistym ryzykiem pozostawienia debugowania na produkcji, var_dump() ma jeszcze jedną wadę: przy dużych obiektach (np. Magento\Sales\Model\Order) wypluje dziesiątki tysięcy linii, które praktycznie nic Ci nie powiedzą. Xdebug rozwiązuje oba problemy.

Instalacja Xdebug 2.x na PHP 7.2

# Sprawdź wersję PHP i arch
php -v
php -i | grep "PHP Extension Build"

# Instalacja przez pecl
pecl install xdebug

# Lub przez apt (Ubuntu/Debian)
sudo apt-get install php7.2-xdebug

Po instalacji dodaj do php.ini (lub osobnego pliku 20-xdebug.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

Uwaga dla Magento: ustaw max_nesting_level na minimum 512. Magento ma głęboko zagnieżdżone wywołania DI i przy niższym limicie Xdebug zatrzyma skrypt zbyt wcześnie.

Konfiguracja w PHPStorm

W PHPStorm wejdź w Settings > PHP > Debug i upewnij się, że port ustawiony jest na 9000 (Xdebug 2.x) lub 9003 (Xdebug 3.x – o tym w przyszłości). Następnie:

1. Kliknij ikonę słuchawki (Start Listening for PHP Debug Connections)
2. Postaw breakpoint w kodzie (klik na numer linii)
3. Wywołaj URL z parametrem ?XDEBUG_SESSION_START=PHPSTORM lub użyj rozszerzenia Xdebug Helper w przeglądarce

Praktyczny przykład – debugowanie pluginu Magento

Załóżmy, że masz plugin modyfikujący cenę produktu i cena jest błędna. Zamiast sypać var_dump() po całym kodzie:

<?php

namespace Vendor\Module\Plugin;

use Magento\Catalog\Model\Product;

class PricePlugin
{
    public function afterGetPrice(Product $subject, float $result): float
    {
        // Postaw breakpoint na linii poniżej
        // PHPStorm zatrzyma wykonanie i pokaże $subject, $result
        // oraz cały call stack – skąd zostało wywołane getPrice()
        $modifiedPrice = $result * 0.9;

        return $modifiedPrice;
    }
}

Przy breakpoincie na $modifiedPrice widzisz w PHPStorm dokładnie: wartość $result przekazaną przez Magento, obiekt $subject z pełnymi danymi produktu, a w panelu Debug > Frames – pełny stos wywołań. To o niebo więcej informacji niż jakikolwiek var_dump().

Bonus: Xdebug + var_dump na sterydach

Nawet jeśli nie używasz zdalnego debugowania, samo zainstalowanie Xdebug poprawia wyjście var_dump() – dostaniesz kolorowe, sformatowane drzewo zamiast ściany tekstu. Przydatne w CLI przy pisaniu skryptów migracyjnych.

Podsumowanie

Konfiguracja Xdebug zajmuje 15-20 minut i zwraca się po pierwszej sesji debugowania złożonego problemu. Jeśli pracujesz z Magento 2, gdzie jeden request może przechodzić przez kilkanaście pluginów i interceptorów – to absolutne must-have. var_dump() zostawmy dla naprawdę trywialnych przypadków.