Debugowanie projektów PHP z użyciem XDebug

XDebug to potężne narzędzie do debugowania, profilowania wydajności i analizy pokrycia kodu w PHP. Integracja i użycie XDebug w lokalnym środowisku developerskim ServBay znacząco podnosi efektywność pracy oraz jakość kodu w projektach PHP. Dzięki XDebug programista może ustawiać punkty przerwania w kodzie, analizować wartości zmiennych, śledzić stos wywołań funkcji i analizować wąskie gardła w wydajności, co znacząco przyspiesza znajdowanie i rozwiązywanie problemów.

Wprowadzenie do XDebug

XDebug to rozszerzenie PHP dostarczające zaawansowanych możliwości debugowania i profilowania. Obsługuje zdalne debugowanie (najczęściej przez protokół DBGp), ustawianie punktów przerwania, wykonywanie krokowe, śledzenie wartości zmiennych, stack trace, profilowanie wydajności oraz generowanie raportów z pokrycia kodu. XDebug pozwala zrozumieć przebieg wykonywania programu oraz jego stan w trakcie działania, co rozszerza możliwości namierzania i eliminowania błędów.

XDebug oferuje kilka trybów pracy, z których najczęściej wykorzystywany jest tryb debug służący do interaktywnego debugowania z punktami przerwania.

Włączanie i konfiguracja XDebug w ServBay

ServBay domyślnie dostarcza XDebug dla każdej obsługiwanej wersji PHP. Nie musisz pobierać ani kompilować go ręcznie.

1. Włącz rozszerzenie XDebug: Otwórz aplikację ServBay. Przejdź do zakładki Języki-PHP, znajdź wersję PHP, w której chcesz uruchomić XDebug. W sekcji Rozszerzenia odszukaj moduł xdebug i upewnij się, że jest aktywny. Jeśli nie, kliknij, aby włączyć. Po aktywacji może być wymagany restart usługi PHP-FPM (ServBay zwykle robi to automatycznie).

2. Konfiguracja IDE: Skonfiguruj połączenie XDebug w swoim środowisku programistycznym (IDE), np. PHPStorm lub VS Code. Najczęściej wymaga to ustawienia nasłuchiwanego portu (zgodnego z konfiguracją w interfejsie ServBay/XDebug) oraz ewentualnego mapowania ścieżek (tylko jeśli ścieżki projektu lokalnie i na serwerze różnią się – w ServBay zwykle nie jest to wymagane).

   Szczegóły konfiguracji IDE

   Szczegółowe instrukcje dla wybranych IDE (np. PHPStorm, VS Code itd.) znajdziesz w dokumentacji tych IDE lub w artykule Jak włączyć wbudowany Xdebug w ServBay.

Praktyczny przykład: Debugowanie projektu PHP w ServBay

Poniżej pokazujemy, jak przy pomocy przykładowego projektu wykorzystać XDebug do debugowania w środowisku ServBay.

1. Utworzenie strony w ServBay

Najpierw utwórz nowy katalog na projekt w środowisku ServBay:

1. W katalogu głównym ServBay: /Applications/ServBay/www/ utwórz folder, np. servbay-xdebug-app.
2. Otwórz aplikację ServBay, wejdź do sekcji "Witryny".
3. Dodaj nową stronę, wskazując katalog źródłowy na /Applications/ServBay/www/servbay-xdebug-app.
4. Ustaw lokalny adres (np. servbay-xdebug-app.servbay.demo).
5. Wybierz preferowaną wersję PHP i upewnij się, że XDebug jest w niej włączony i skonfigurowany zgodnie z wcześniejszymi krokami.
6. Zapisz i zastosuj zmiany. ServBay automatycznie skonfiguruje Caddy/Nginx oraz zaktualizuje plik hosts (lub ustawi DNS ServBay).

2. Struktura projektu i kod przykładowy

W katalogu /Applications/ServBay/www/servbay-xdebug-app/ utwórz następującą strukturę:

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

src/Calculator.php:

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // Ustaw punkt przerwania w tej linii
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

index.php:

<?php
// Załaduj autoloader Composer, jeśli go używasz
// W przypadku braku Composera dostosuj sposób ładowania klasy
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Przykład debugowania:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Suma: " . $sum . "\n";
echo "Różnica: " . $difference . "\n";

echo "Gotowe.\n";
?>

Uwaga: Założono, że używasz Composera i linii require __DIR__ . '/vendor/autoload.php';. Jeśli testujesz tylko prosty przykład, możesz usunąć tę linię i zamienić use App\Calculator; na require __DIR__ . '/src/Calculator.php';.

3. Ustaw punkt przerwania

W swoim IDE (np. PHPStorm) otwórz plik /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php. Kliknij na numerze linii przy instrukcji return $a + $b; w metodzie add, aby dodać punkt przerwania.

4. Uruchom sesję debugowania

1. W swoim IDE uruchom nasłuchiwanie połączeń XDebug. W PHPStorm zwykle jest to przycisk „Start Listening for PHP Debug Connections” (ikona słuchawki lub żuczka na pasku eksploratora).
2. W przeglądarce wejdź na stronę index.php Twojego projektu ServBay: https://servbay-xdebug-app.servbay.demo/index.php.
3. Jeśli masz ustawione xdebug.start_with_request na trigger, upewnij się, że dodałeś wyzwalacz XDebug (np. poprzez rozszerzenie do przeglądarki lub wejście na adres https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. Przebieg debugowania

1. Po wejściu na index.php i wywołaniu sesji XDebug, połączenie zostanie nawiązane z IDE, a wykonywanie kodu zostanie zatrzymane na ustawionym punkcie przerwania.
2. IDE przełączy się w tryb debugowania, pokazując kod zatrzymany właśnie w metodzie add pliku Calculator.php.

6. Sprawdzanie wartości zmiennych

1. W panelu debugowania IDE widoczne są m.in. aktualna linia wykonania, stos wywołań (Call Stack) i wartości zmiennych.
2. W zakładce „Variables” możesz sprawdzić wartość zmiennych w bieżącym scope. Przykładowo $a powinno mieć wartość 5, a $b wartość 3.

7. Wykonywanie krokowe

1. Używaj dedykowanych przycisków do nawigacji krokowej: Step Over (F8), Step Into (F7), Step Out (Shift+F8).
   • Step Over: wykonuje bieżącą linię bez wchodzenia w wywołania funkcji.
   • Step Into: wchodzi do środka wywołanej funkcji.
   • Step Out: kończy wykonywanie obecnej funkcji i wraca do miejsca wywołania.
2. Dzięki krokowej nawigacji prześledzisz działanie programu linia po linii oraz zmiany wartości zmiennych.

8. Kontynuacja działania programu

1. Kliknij ikonę „Resume Program” (zwykle zielona strzałka lub F9), by wznowić wykonywanie do kolejnego punktu przerwania lub do końca skryptu.

9. Sprawdzenie wyników

1. Po zakończeniu działania kodu sprawdź wynik w przeglądarce (lub, jeśli debugujesz CLI — w terminalu). Dla powyższego przykładu powinieneś zobaczyć:

   Przykład debugowania:
   Suma: 8
   Różnica: 2
   Gotowe.

Wskazówki i uwagi

• Zapora sieciowa: Upewnij się, że firewall nie blokuje portu nasłuchu, z którego korzysta IDE (domyślnie 9003).
• Konflikt portów: Zweryfikuj, czy wybrany port dla XDebug nie jest zajęty przez inny proces.
• Wydajność: Jeśli xdebug.mode=debug oraz xdebug.start_with_request=yes, każda prośba do PHP inicjuje debugowanie, co poważnie obniża wydajność strony. Po zakończeniu sesji debugowania wyłącz XDebug lub ustaw xdebug.start_with_request na trigger.
• Debugowanie CLI: XDebug umożliwia także debugowanie skryptów CLI PHP. W tym celu ustaw odpowiednie zmienne środowiskowe lub użyj dedykowanych parametrów; szczegółowe instrukcje znajdziesz w oficjalnej dokumentacji XDebug.
• Wersja i konfiguracja IDE: Konfiguracja może się różnić w zależności od wersji IDE. Jeśli napotkasz trudności, sprawdź instrukcję obsługi swojego środowiska.

FAQ – Najczęstsze pytania

Q: Moje IDE nie łączy się z XDebug. Co mogę zrobić?

A: Sprawdź następujące kwestie:

1. Upewnij się, że XDebug jest włączony w odpowiedniej wersji PHP w ServBay.
2. Skontroluj w pliku php.ini ustawienia xdebug.mode, xdebug.client_host, xdebug.client_port i porównaj z konfiguracją IDE.
3. Przy ustawieniu xdebug.start_with_request = trigger — czy na pewno dodano wyzwalacz (GET/POST, Cookie, nagłówek)?
4. Zapora sieciowa pozwala na ruch na porcie XDebug.
5. IDE faktycznie nasłuchuje na wskazanym porcie.

Q: Po włączeniu XDebug strona mocno spowalnia. Dlaczego?

A: Najprawdopodobniej xdebug.start_with_request ustawione jest na yes. Debugowanie startuje dla wszystkich żądań PHP, co znacząco spowalnia aplikację. Zalecamy przełączyć na trigger i debugować tylko wtedy, gdy to konieczne.

Q: Czy XDebug obsługuje debugowanie zapytań AJAX?

A: Tak. Debugowanie żądań AJAX działa analogicznie do zwykłych żądań HTTP. Upewnij się, że przekazywane są wyzwalacze XDebug (najczęściej przez Cookie lub nagłówek HTTP).

Q: Czy ServBay i XDebug współpracują z VS Code lub innymi IDE poza PHPStorm?

A: Jak najbardziej. Wbudowany XDebug w ServBay to standardowe rozszerzenie PHP, współpracuje ze wszystkimi IDE obsługującymi protokół DBGp, m.in. VS Code (z rozszerzeniem PHP Debug), NetBeans, Eclipse i wiele innych. Sposób konfiguracji jest podobny: należy ustawić poprawny port nasłuchu w IDE.

Podsumowanie

Dzięki XDebug zintegrowanemu z ServBay możesz z łatwością debugować projekty PHP w lokalnym środowisku. Opanowanie technik stawiania punktów przerwania, inspekcji zmiennych czy wykonywania krokowego pozwoli Ci znacznie szybciej lokalizować błędy i dbać o jakość kodu. Łączenie tych możliwości z wygodnym zarządzaniem środowiskiem w ServBay sprawia, że XDebug staje się niezbędnym narzędziem w codziennej pracy każdego programisty PHP. Zacznij debugować z XDebug w ServBay i doświadcz płynnej, efektywnej pracy nad projektami PHP!