PHP Hata Ayıklama: Xdebug Kurulumu ve Yapılandırması

Yazar:komut.io ekibi PHP Sürüm Yönetimi ve Yapılandırma
0 Yorum

PHP geliştirme yaparken en sinir bozucu anlardan biri, bir hata var ama tam olarak nerede olduğunu bulamıyorsun. var_dump() ve die() ikilisiyle saatlerce uğraşmak yerine, Xdebug gibi profesyonel bir araç kullanmak hem zaman kazandırır hem de seni gerçek anlamda bir geliştirici seviyesine taşır. Bu yazıda Xdebug’ı sıfırdan kurup yapılandıracağız, IDE entegrasyonunu gerçekleştireceğiz ve production benzeri ortamlarda nasıl kullanacağımızı ele alacağız.

Xdebug Nedir ve Neden Kullanmalısın?

Xdebug, PHP için geliştirilmiş açık kaynaklı bir debugger ve profiler eklentisidir. Temel olarak şunları yapabilirsin:

  • Step debugging: Kodu satır satır çalıştırarak değişken değerlerini izleme
  • Stack trace: Hata anında çağrı yığınını detaylı görme
  • Code coverage: Test sırasında hangi kod satırlarının çalıştığını ölçme
  • Profiling: Uygulamanın hangi fonksiyonlarda ne kadar zaman harcadığını analiz etme

var_dump() ile debug yapıyorsan ve bunu normal karşılıyorsan, bu yazıyı okuduktan sonra fikrini değiştireceğine eminim. Xdebug bir kez kurulduktan sonra, bir daha eskiye dönmek istemiyorsun.

Kurulum Öncesi Hazırlık

PHP Sürümünü Kontrol Etme

Xdebug kurulumu yapmadan önce sisteminizde hangi PHP sürümünün çalıştığını ve hangi mimari için derlendiğini bilmek gerekiyor. Xdebug 3.x, PHP 7.2 ve üzerini destekliyor.

php -v
php -i | grep -i "thread safety"
php -i | grep -i "architecture"

Thread safety durumuna dikkat et. Eğer çıktıda Thread Safety => disabled görüyorsan NTS (Non-Thread Safe), enabled görüyorsan TS (Thread Safe) sürümünü kurman gerekiyor. Özellikle Apache mod_php kullanıcıları çoğunlukla TS sürümüne ihtiyaç duyar.

Mevcut PHP Eklentilerini Listeleme

php -m | grep -i xdebug
php --ini

İkinci komut, PHP’nin hangi php.ini dosyasını kullandığını gösterir. Bu dosyanın konumunu not al, kurulum sonrasında burayı düzenleyeceğiz.

Linux Üzerinde Xdebug Kurulumu

Ubuntu/Debian Tabanlı Sistemler

En pratik yol pecl veya doğrudan paket yöneticisi üzerinden kurulumdur.

# Önce build araçlarını kur
sudo apt update
sudo apt install php-dev php-pear gcc make autoconf

# PECL üzerinden kur
sudo pecl install xdebug

# Alternatif olarak apt ile kur (Ubuntu 20.04+)
sudo apt install php8.1-xdebug

Eğer birden fazla PHP sürümü kullanıyorsan (ki production ortamlarında çok sık karşılaşılan bir durum), sürüme özel kurulum yapman gerekiyor:

# PHP 8.1 için
sudo apt install php8.1-xdebug

# PHP 7.4 için
sudo apt install php7.4-xdebug

# Hangi sürüm için kurulduğunu doğrula
php8.1 -m | grep xdebug

CentOS/RHEL/Rocky Linux Sistemler

# EPEL deposunu etkinleştir
sudo dnf install epel-release

# PHP devel paketini kur
sudo dnf install php-devel php-pear

# PECL üzerinden kur
sudo pecl install xdebug

# Eklenti dosyasının yerini bul
find /usr /lib -name "xdebug.so" 2>/dev/null

Kaynak Koddan Derleme (İleri Seviye)

Özellikle özel derlenmiş PHP sürümleri kullanıyorsan ya da en güncel Xdebug sürümüne ihtiyaç duyuyorsan, kaynak koddan derleme en sağlıklı yoldur:

cd /tmp
git clone https://github.com/xdebug/xdebug.git
cd xdebug
phpize
./configure --enable-xdebug
make
sudo make install

# Kurulum sonrası .so dosyasının konumunu öğren
php -i | grep extension_dir

Windows Üzerinde Xdebug Kurulumu

Windows tarafında işler biraz daha titizlik istiyor. Önce [xdebug.org/wizard](https://xdebug.org/wizard) adresine git. Bu sihirbaz sana tam olarak hangi DLL dosyasını indirmen gerektiğini söylüyor.

Sihirbazı kullanmak için php -i çıktısını kopyala ve siteye yapıştır. Sistem sana uygun binary’yi otomatik belirliyor. Ardından:

  • İndirilen .dll dosyasını PHP’nin ext klasörüne koy (örneğin C:phpext)
  • php.ini dosyasına gerekli satırları ekle
  • Web sunucusunu veya PHP-FPM’i yeniden başlat

php.ini Yapılandırması

Xdebug kurulduktan sonra asıl iş php.ini veya ayrı bir .ini dosyası üzerinden yapılandırmaya geliyor. Xdebug 3.x ile birlikte yapılandırma sistemi köklü biçimde değişti ve çok daha sade hale geldi.

Temel Yapılandırma Dosyası

# php.ini konumunu bul
php --ini | grep "Loaded Configuration"

# Ya da FPM kullanıyorsan
php-fpm8.1 --ini

# Özel bir xdebug.ini dosyası oluştur (önerilen yöntem)
sudo nano /etc/php/8.1/mods-available/xdebug.ini
; Xdebug 3.x yapılandırması
zend_extension=xdebug

; Xdebug modu: develop, debug, coverage, profile, trace
xdebug.mode=develop,debug

; Dinlenecek host ve port
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

; Debug oturumunu başlatmak için trigger
xdebug.start_with_request=trigger

; Log dosyası (gerektiğinde etkinleştir)
; xdebug.log=/var/log/xdebug.log
xdebug.log_level=0

; IDE key tanımla
xdebug.idekey=VSCODE

xdebug.mode parametresi Xdebug 3.x’in en önemli yeniliği. Tek bir değer yerine virgülle ayrılmış birden fazla mod tanımlayabiliyorsun:

  • develop: Geliştirilmiş hata mesajları ve var_dump çıktısı
  • debug: Step debugging özelliği
  • coverage: Kod kapsama analizi
  • profile: Performans profiling
  • trace: Fonksiyon çağrı takibi

Yapılandırmayı Etkinleştirme

# Ubuntu/Debian üzerinde
sudo phpenmod xdebug

# Etkinleştirildi mi kontrol et
php -m | grep xdebug

# PHP-FPM yeniden başlat
sudo systemctl restart php8.1-fpm

# Apache kullanıyorsan
sudo systemctl restart apache2

# Nginx + FPM kullanıyorsan sadece FPM yeterli
sudo systemctl reload php8.1-fpm

VS Code ile Xdebug Entegrasyonu

PHP Debug eklentisi olmadan VS Code ile Xdebug kullanmak mümkün değil. Felix Becker’ın geliştirdiği PHP Debug eklentisini kur.

Kurulum sonrası .vscode/launch.json dosyasını şu şekilde yapılandır:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html/myapp": "${workspaceFolder}"
            },
            "xdebugSettings": {
                "max_data": 65535,
                "show_hidden": 1,
                "max_children": 128,
                "max_depth": 5
            }
        },
        {
            "name": "Launch PHP Script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]
}

pathMappings özelliği özellikle Docker veya uzak sunucu kullanıyorsan kritik öneme sahip. Sunucudaki dosya yolunu lokal çalışma dizinindeki karşılığıyla eşliyorsun.

PhpStorm ile Entegrasyon

PhpStorm kullanıcıları için entegrasyon daha da pürüzsüz çünkü IDE Xdebug’ı yerleşik olarak destekliyor.

PhpStorm üzerinde yapman gerekenler:

  • File > Settings > PHP > Debug kısmına git
  • Xdebug port olarak 9003 gir (varsayılan değer Xdebug 3 ile değişti, eski sürümlerde 9000 idi)
  • Start Listening for PHP Debug Connections butonuna tıkla ya da telefon simgesine tıkla

Tarayıcı tarafında debug oturumu başlatmak için browser eklentisi kullanabilirsin. Xdebug Helper eklentisi hem Chrome hem Firefox için mevcut.

Docker Ortamında Xdebug Yapılandırması

Gerçek dünya senaryolarının büyük çoğunluğu artık Docker üzerinde dönüyor. Docker içinde Xdebug yapılandırması birkaç ekstra adım gerektiriyor.

FROM php:8.1-fpm

# Xdebug kur
RUN pecl install xdebug 
    && docker-php-ext-enable xdebug

# Özel php.ini kopyala
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

Docker için Xdebug yapılandırması önemli bir fark içeriyor. Container’dan host makineye erişmek için host.docker.internal kullanman gerekiyor:

# xdebug.ini - Docker için
cat > xdebug.ini << 'EOF'
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.log_level=0
EOF

Linux’ta host.docker.internal her zaman çalışmayabiliyor. Bu durumda alternatif bir yaklaşım kullanabilirsin:

# docker-compose.yml içinde host IP'yi ortam değişkeni olarak geç
environment:
  XDEBUG_CONFIG: "client_host=${HOST_IP}"
# .env dosyasında HOST_IP tanımla
HOST_IP=$(ip route show default | awk '/default/ {print $3}')
echo "HOST_IP=$HOST_IP" >> .env

Xdebug ile Profiling Yapma

Debug’ın ötesinde, Xdebug’ın profiling özelliği gerçekten değerli. Bir PHP uygulamasının neden yavaş çalıştığını bulmak için profiling mükemmel bir araç.

; profiling modunu etkinleştir
xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug_profiles
xdebug.profiler_output_name=cachegrind.out.%p.%r
# Profil çıktısını tetikle
curl "http://localhost/myapp/slow-endpoint.php?XDEBUG_PROFILE=1"

# Çıktı dosyasını kontrol et
ls -lh /tmp/xdebug_profiles/

# KCachegrind ile analiz et (Linux)
sudo apt install kcachegrind
kcachegrind /tmp/xdebug_profiles/cachegrind.out.12345.xxx

QCachegrind (Windows/Mac için) veya KCachegrind ile cachegrind dosyasını açtığında hangi fonksiyonun ne kadar zaman ve bellek harcadığını grafiksel olarak görebiliyorsun.

Xdebug Trace Özelliği

Bir fonksiyonun nasıl çağrıldığını tüm detaylarıyla kayıt altına almak istiyorsan trace modu tam sana göre.

xdebug.mode=trace
xdebug.output_dir=/tmp/xdebug_traces
xdebug.trace_output_name=trace.%c.%p
# Trace'i komut satırından tetikle
XDEBUG_MODE=trace php -r "
function hesapla($x) {
    return $x * 2;
}
echo hesapla(21);
"

# Oluşan trace dosyasını oku
cat /tmp/xdebug_traces/trace.*.xt

Sık Karşılaşılan Sorunlar ve Çözümleri

Port Çakışması

Xdebug 2.x varsayılan olarak 9000 portunu kullanırken, Xdebug 3.x 9003’e geçti. PHP-FPM de 9000 portunu dinliyor. Bu yüzden 9003 kullanmak çok daha temiz bir seçenek.

# 9003 portunu hangi servis kullanıyor kontrol et
sudo ss -tlnp | grep 9003
sudo lsof -i :9003

Xdebug Tetiklenmiyor

start_with_request=trigger kullandığında debug oturumunu tetiklemek için birkaç yol var:

# Komut satırından
XDEBUG_SESSION=VSCODE php script.php

# HTTP isteğiyle
curl "http://localhost/index.php" -b "XDEBUG_SESSION=VSCODE"

# GET parametresiyle
curl "http://localhost/index.php?XDEBUG_SESSION_START=VSCODE"

IDE Bağlantı Alamıyor

Firewall kurallarını kontrol etmeyi unutma. Özellikle Docker veya VM kullanıyorsan:

# UFW ile porta izin ver
sudo ufw allow 9003/tcp

# iptables ile
sudo iptables -A INPUT -p tcp --dport 9003 -j ACCEPT

# Xdebug log aktif et ve kontrol et
sudo nano /etc/php/8.1/mods-available/xdebug.ini
# xdebug.log=/tmp/xdebug.log satırını ekle
tail -f /tmp/xdebug.log

Performans Sorunları

Xdebug production’da kesinlikle aktif olmamalı. Xdebug etkin olduğunda PHP performansı gözle görülür biçimde düşebiliyor. Geliştirme ortamında bile sadece ihtiyaç duyduğunda aktif etmek en iyi pratik.

# Xdebug'ı geçici devre dışı bırak
sudo phpdismod xdebug
sudo systemctl restart php8.1-fpm

# Tekrar etkinleştir
sudo phpenmod xdebug
sudo systemctl restart php8.1-fpm

Alternatif olarak XDEBUG_MODE=off ortam değişkeniyle Xdebug’ı yüklemeden devre dışı bırakabilirsin. Bu yöntem, farklı ortamlar için .env dosyasında yönetim açısından oldukça pratik.

# .env dosyasında
XDEBUG_MODE=off  # production
XDEBUG_MODE=debug  # development

Breakpoint ve Watch Expression Kullanımı

VS Code veya PhpStorm’da debug yaparken en güçlü özellikler breakpoint ve watch expression. Bir breakpoint koyduğunda PHP o satıra geldiğinde duruyor ve tüm değişken durumlarını inceleyebiliyorsun.

Özellikle döngü içindeki değişkenleri takip etmek için conditional breakpoint özelliği hayat kurtarıcı. VS Code’da bir breakpoint üzerinde sağ tıklayıp “Edit Breakpoint” seçeneğiyle koşul tanımlayabilirsin. Örneğin $i === 500 koşulunu tanımlarsan, 500’üncü iterasyonda kod duruyor ve başa sarılmadan direkt o noktayı inceleyebiliyorsun.

Sonuç

Xdebug kurulumu ilk bakışta karmaşık görünebilir, özellikle Docker veya çoklu PHP sürümü ortamlarında. Ama bir kere doğru kurulduktan sonra, geliştirme sürecini tamamen dönüştürüyor. var_dump() ile saatlerce uğraşmak yerine breakpoint koyuyor, kodu adım adım yürütüyor ve değişken değerlerini gerçek zamanlı izliyorsun.

Özetlemek gerekirse:

  • Xdebug 3.x ile default port 9003 oldu, bunu IDE yapılandırmanda doğru gir
  • Docker ortamında host.docker.internal kullan, Linux’ta bu çalışmıyorsa host IP’yi elle belirt
  • xdebug.mode parametresini ihtiyaca göre ayarla, her şeyi aynı anda aktif etme
  • Production’da Xdebug asla çalışmamalı, ya tamamen kaldır ya da XDEBUG_MODE=off kullan
  • Profiling özelliğini performans sorunlarını analiz etmek için kullan, KCachegrind ile görselleştir

PHP geliştirici olarak Xdebug’ı araç setinin vazgeçilmez bir parçası haline getirmek, seni hem daha hızlı hem de çok daha güvenilir bir şekilde çalışmanı sağlıyor. Bir dahaki debug oturumunda var_dump() yazmadan önce bir düşün, o breakpoint seni kurtarabilir.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir