Xdebug veya PHP Debugger ile hata ayıklama, elle ya da bir yapay zekâyla

JumPHP IDE'nin gerçek bir adım adım hata ayıklayıcısı vardır: programı bir satırda durdurur, değişkenlere bakar, birini değiştirir ve adım adım devam edersiniz. Xdebug'ın protokolü olan DBGp konuşur, bu yüzden iki motoru yönetebilir:

• Xdebug, klasik olan (varsayılan);
• PHP Debugger, daha yeni bir DBGp hata ayıklayıcısı, ücretsiz ve açık kaynak, Xdebug'ın ayarlarıyla uyumlu, neredeyse sıfır ek yük.

IDE'de ikisi de aynı şekilde çalışır. Hata ayıklayıcıyı bir yapay zekâya (Claude Code) da verebilirsiniz: kesme noktalarını kendisi koyar, programı çalıştırır, değişkenleri okur ve hatayı kendisi bulur.

Hangi motoru seçmeli

Pratikte: günlük hata ayıklama, uzun çalıştırmalar (600 kare oynayan bir oyun, bir test paketi) ve yapay zekâyla hata ayıklama için PHP Debugger'ı seçin. Async runtime ile (iş parçacıkları) çalışıyorsanız ya da yalnızca Xdebug'ın yaptığı bir şeye ihtiyacınız varsa Xdebug'da kalın. IDE'de ikisi birbirinin yerine kullanılabilir, yani aynı projede ikisini de deneyebilirsiniz.

PHP Debugger'ın kendi sayfası hiçbir kıyaslama değeri vermez: yalnızca hata ayıklamadığınız sürece maliyetin neredeyse sıfır olduğunu söyler. Fark sizin için önemliyse kendi projenizde ölçün.

IDE'de motoru seçmek

• Başlıktaki Hata ayıkla düğmesi (Çalıştır'ın yanındaki böcek, Shift+F9) bir menü açar: Şununla hata ayıkla (bu çalıştırma için Xdebug veya PHP Debugger) ve Varsayılan motor (bundan sonra düz bir tıklamanın kullanacağı motor). Düğmeye sağ tıklamak aynı menüyü açar.
• Belirli bir motorla ilk çalıştırma bir kez Docker imajı oluşturur (yaklaşık bir dakika). Sonrakiler hemen başlar.
• Program hata ayıklayıcıya hiç bağlanmazsa (daha önce bitti ya da 3 dakika sonra hâlâ bir şey yok) bir bildirim sizi uyarır. Nedeni genellikle Çalıştır penceresinin çıktısında yazar.

Motoru terminalden seçmek

Her şey her zamanki gibi bin/jumphp üzerinden yapılır:

# Xdebug (default)
JUMPHP_XDEBUG=9003 bin/jumphp test pong

# PHP Debugger
JUMPHP_DEBUGGER=php-debugger JUMPHP_XDEBUG=9003 bin/jumphp test pong

• JUMPHP_XDEBUG=<port> adım adım hata ayıklamayı açar: PHP, bilgisayarınızın o portunu dinleyen bir hata ayıklayıcıya bağlanır (composer, phpstan ve php -l onsuz çalışır).
• JUMPHP_DEBUGGER=xdebug|php-debugger motoru seçer (varsayılan xdebug).
• php-debugger ile bin/jumphp, masaüstü imajından yola çıkarak docker/desktop-phpdebugger imajını bir kez oluşturur; masaüstü imajı onsuz kalır.
• Async runtime'da (PHP 8.6) "PHP Debugger does not run on PHP 8.6 (async runtime): Xdebug is used" iletisi gösterilir ve Xdebug çalışır.

IDE'de elle hata ayıklamak

1. Kesme noktası: bir PHP satırının solundaki oluğa tıklayın. Sağ tık bir koşul verir (bir PHP ifadesi: yalnızca doğru olduğunda durur, örn. $this->score < 0); Ctrl+F8 imlecin olduğu yere bir tane koyar. Kesme noktaları proje başına saklanır ve siz düzenledikçe satırlarını izler.
2. Hata ayıkla (Shift+F9): program çalışır ve ilk kesme noktasında durur. Satır işaretlenir ve Debug araç penceresi açılır.
3. Bakın: çağrı yığını (değişkenlerini görmek için bir çerçeveye tıklayın), istenince okunan bir ağaç olarak değişkenler, watches ve programın durduğu yerde herhangi bir PHP ifadesini değerlendirmek için bir alan.
4. Bir değeri değiştirmek: bir değişkene çift tıklayın veya F2, bir PHP ifadesi yazın (9, "Ada", [1, 2], null) ve yeni değerle devam edin.
5. Hareket: Devam et F9, Üzerinden Geç F8, İçine Gir F7, Dışına Çık Shift+F8, İmlece Kadar Çalıştır Alt+F9, Durdur.
6. İstisnalar: İstisnalarda Dur… (Debug penceresinin uyarı simgesi): * veya sınıf adları (TypeError, App\GameOver). İstisna, yakalansın ya da yakalanmasın, fırlatıldığı yerde durur ve hangisi olduğunu iletisiyle birlikte gösterir.

Fareyle üzerine gelince inceleyici (bir sonraki IDE güncellemesinde): program bir kesme noktasında durmuşken, düzenleyicide bir değişkenin üzerine gelin; değerinin Copy ve Edit düğmeli genişletilebilir bir ağacını görürsünüz.

Oyunlar için bir ipucu: headless çalıştırmalarda (test, shot) hata ayıklayın: bir pencerenin içinde durdurulan oyun, siz devam ettirene kadar donar.

Bir yapay zekâyla hata ayıklamak

Bir yapay zekâ, bir hata ayıklayıcıyla var_dump()'tan daha iyi hata ayıklar: gerçek değerleri, her seferinde tek bir soruyla okur ve kodunuzda hiçbir şeyi değiştirmez. İki MCP sunucusu vardır. Aynı anda yalnızca birini kullanın (ikisi de 9003 portunu dinler).

1. JumPHP sunucusu: bin/jumphp debug

IDE'nin kendi hata ayıklayıcısı bir MCP sunucusu olarak (Docker'da, Xdebug ile çalışır):

claude mcp add jumphp-debug -- bin/jumphp debug

Araçları:

Yollar projeye görelidir. Claude programı kendisi, arka planda, JUMPHP_XDEBUG=9003 ile başlatır, sonra debug_wait çağırır.

2. PHP Debugger'ın sunucusu: dbgp mcp

PHP Debugger, kendi MCP sunucusunu dbgp adlı küçük bir programın içinde getirir (MIT lisansı; Linux ve macOS, amd64 ve arm64; Windows amd64).

# install (macOS / Linux)
curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | sh
dbgp -version

# for this project / for all your projects
claude mcp add dbgp -- dbgp mcp
claude mcp add --scope user dbgp -- dbgp mcp

Claude Code içinde /mcp bağlı olduğunu gösterir. Araçları, PHP Debugger'ın belgelerindeki adlarıyla:

• bağlantı: status, listen, unlisten, sessions, wait_for_session, detach;
• kesme noktaları: add_breakpoint, remove_breakpoint, breakpoints;
• çalıştırma: continue, wait_for_stop, stop;
• bakma: stack, variables, variable, variable_value, source, output, warnings;
• eyleme geçme: eval, set_variable;
• Docker / uzak: add_path_mapping, path_mappings.

Yararlı bayraklar (hepsi için dbgp mcp -h): -php-port PORT (PHP'nin bağlandığı port, varsayılan 9003), -mcp-port PORT, -idekey KEY, -map LOCAL=REMOTE (bir yol eşlemesi, tekrarlanabilir) ve eval, set_variable ile koşullu kesme noktalarını yasaklayan -no-eval: yapay zekâ yalnızca bakabilir. Değerleri gizlemez, yani parolalar ve anahtarlar ona görünür kalır.

bin/jumphp üzerinden JUMPHP_DEBUGGER=php-debugger bin/jumphp debug sizin için dbgp mcp başlatır (bilgisayarınızda dbgp kurulu olmalıdır). Sonra programı aynı motorla başlatın:

JUMPHP_DEBUGGER=php-debugger JUMPHP_XDEBUG=9003 bin/jumphp test pong

Örnek bir oturum

Siz, Claude Code'a:

pong oyununun skoru, top sol raketi geçince 1 yerine 2 artıyor. Hata ayıklayıcıyı kullan, var_dump'ı değil. Skorun artırıldığı yere bir kesme noktası koy (PlayScene'e bak), bin/jumphp test pong komutunu JUMPHP_XDEBUG=9003 ile çalıştır, orada dur, değişkenleri oku ve nedenini söyle. Nedeni bana göstermeden düzeltme yapma.

Yapay zekâ bundan sonra yukarıdaki araçlarla şunları yapar:

1. bir puan ekleyen satırı bulur ve oraya bir kesme noktası koyar; satır her karede çalışıyorsa bir koşulla ($this->ballX < 0);
2. testi arka planda başlatır ve durmayı bekler (debug_wait / wait_for_stop);
3. bu satırı kimin çağırdığını görmek için $this->score, $this->scored ve yığını okur;
4. ikinci çağıranı görmek için bir kez dışarı çıkar (debug_step step_out): puan iki kez sayılıyor;
5. hiçbir şeyi düzenlemeden fikrini sınar: $this->scored'a bir değer verir (debug_set_value / set_variable) ve skorun doğru kaldığını görmek için devam eder;
6. ancak o zaman kodu düzenler ve testi kesme noktası olmadan yeniden çalıştırır.

İpuçları

• Açıkça söyleyin: "hata ayıklayıcıyı kullan". Aksi halde bir ajan çoğu zaman var_dump()'a döner.
• Hatayı gösteren komutu, ne beklediğinizi ve nereden şüphelendiğinizi verin.
• Küçük adımlar: birkaç step_over, sonra bakmak. Koşullu bir kesme noktası ($enemy->hp <= 0), 600 kareyi adım adım geçmekten iyidir.
• Değişkenleri okumasına ve ifadeleri değerlendirmesine izin verin: var_dump() yok, echo yok, sonradan temizlenecek bir şey yok.
• Pencere yerine headless çalıştırmaları (test, shot, php) tercih edin.
• Gizli bilgiler: yapay zekâ okuduğu her değişkeni görür (parolalar, token'lar, API anahtarları). Test verileriyle hata ayıklayın ve programınızda kod çalıştırmasını istemiyorsanız dbgp ile -no-eval kullanın.
• Hata ayıklamadığınız bir projede bir hata ayıklayıcının MCP sunucusunu bağlı bırakmayın: claude mcp remove ile kaldırın.

Sorun giderme

Hiçbir şey durmuyor / "did not connect". Portu dinleyen bir hata ayıklayıcı var mı (IDE'nin Debug penceresi veya bir MCP sunucusu)? Program JUMPHP_XDEBUG=<port> ile ve dinleyiciyle aynı motorla başlatılmalıdır.

Port zaten kullanımda. 9003'te iki dinleyici: IDE ile bin/jumphp debug (veya dbgp mcp), ya da iki IDE. Birini durdurun ya da başka bir port kullanın: JUMPHP_XDEBUG=9010 ile JUMPHP_DEBUG_PORT=9010 bin/jumphp debug, veya dbgp -php-port 9010 mcp.

Kesme noktasına hiç ulaşılmıyor. Kod içermeyen bir satırda (yorum, boş satır, kapanış parantezi) ya da programın hiç yüklemediği bir dosyada. Nerede olduğunu görmek için debug_state çalıştırın / yığına bakın. Bir -map veya IDE ile: yollar eşleşmelidir (aşağıda).

Docker'daki yollar. bin/jumphp projenizi kapsayıcıda /workspace altına bağlar: hata ayıklayıcı file:///workspace/... der. IDE ve bin/jumphp debug bunu projenin dosyalarıyla kendiliğinden eşler ve verdiğiniz yollar projeye görelidir. Yalnızca dbgp mcp ile klasörleri eşleyin: dbgp mcp -map /home/you/project=/workspace.

PHP 8.6 (async runtime). PHP Debugger orada çalışmaz: Xdebug kullanılır. PHP Debugger'ı kullanmak için varsayılan runtime'da (PHP 8.5) hata ayıklayın ya da oturum boyunca runtime: async'i kaldırın.

Tarayıcı oyunları. Hata ayıklayıcı masaüstü runtime'ında çalışır. Tarayıcıda hatayı masaüstünde bin/jumphp test veya shot ile yeniden üretin.

Ayrıca bakın: Kod yazmak, çalıştırmak ve test etmek, IDE'de Claude ve IDE Remote.