Windows, Docker ve VSCode ile Kusursuz PHP Debug Ortamı Kurulumu

Windows üzerinde PHP geliştirirken performans sorunları ve "dosya yolunda çalışmama" gibi hatalardan sıkıldınız mı? Bu rehberde; Apache, MySQL ve Xdebug 3 kullanarak, VSCode ile tam senkronize çalışan, yüksek performanslı bir geliştirme ortamını nasıl kuracağınızı anlatıyorum.

⚠️ Gereksinimler

• Windows 10/11 (WSL 2 yüklü olması önerilir).

• Docker Desktop.

• VSCode.

---

1. Proje Yapısı

Öncelikle projenizin ana dizininde (C:\Users\user\htdocs_debug) aşağıdaki klasör ve dosyaları oluşturun:

• /html (Kodlarınız burada olacak)

• /mysql_data (Veritabanı verileriniz burada saklanacak)

• docker-compose.yml

• Dockerfile

---

2. Docker Yapılandırması

docker-compose.yml dosyanıza aşağıdaki içeriği ekleyin. Bu yapı, Apache'yi 8888 portunda, MySQL'i ise 3312 portunda çalıştıracaktır:

YAML

version: '3.8'
services:
  web:
    build: .
    container_name: phpserver_debug
    ports:
      - "8888:80"
    volumes:
      - ./html:/var/www/html
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - lamp-network
  db:
    image: mysql:8.0
    container_name: mysql_debug
    restart: always
    ports:
      - "3312:3306"
    environment:
      MYSQL_DATABASE: debug_db
      MYSQL_USER: debug_user
      MYSQL_PASSWORD: debug_password
      MYSQL_ROOT_PASSWORD: root_password
    volumes:
      - ./mysql_data:/var/lib/mysql
    networks:
      - lamp-network
networks:
  lamp-network:
    driver: bridge

Dockerfile dosyanızda ise PHP sürücülerini ve Xdebug ayarlarını yapıyoruz:

Dockerfile

FROM php:8.2-apache
RUN docker-php-ext-install pdo pdo_mysql
RUN pecl install xdebug && docker-php-ext-enable xdebug

# Xdebug 3 Yapılandırması
RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_port=9003" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

---

pecl install xdebug: PECL (PHP Extension Community Library) aracılığıyla en son stabil Xdebug sürümünü indirir ve derler.

docker-php-ext-enable xdebug: Resmi PHP Docker imajlarında bulunan yardımcı script'tir. Kurulan extension'ı etkinleştirir ve /usr/local/etc/php/conf.d/ altına docker-php-ext-xdebug.ini dosyası oluşturur. 

&& ile iki komut zincirlenmiş → kurulum başarısız olursa enable aşamasına geçmez.

xdebug.mode=debug: Xdebug'un sadece debug modunda çalışmasını sağlar (Xdebug 3'te çoklu mod desteği var: debug, profiling, trace vb.). Diğer modlar kapalı.

xdebug.client_host=host.docker.internal: Xdebug'un bağlantı kuracağı IDE'nin (VS Code) IP'si. 

host.docker.internal: Docker'ın sağladığı özel DNS adıdır → container'dan ana makineye (host) ulaşır. Mac ve Windows'ta çalışır, Linux'ta bazen ek ayar gerekir.

xdebug.client_port=9003:  Xdebug 3'ün varsayılan portudur (Xdebug 2'de 9000'di). VS Code'un dinleyeceği port ile aynı olmalı.

xdebug.start_with_request=yes:  Her PHP isteğinde otomatik olarak debug oturumu başlatır.  

Avantaj: Tarayıcıda extension veya ?XDEBUG_SESSION_START=1 eklemeye gerek kalmaz. 

Dezavantaj: Production'da kesinlikle kapatılmalı (performans düşer).

xdebug.log=/var/www/html/xdebug.log: Xdebug'un hata ve bağlantı loglarını bu dosyaya yazar.

Bağlantı sorunlarında çok faydalıdır (örneğin "Cannot connect to client"). Dosya izinlerine dikkat!

xdebug.idekey=VSCODE: IDE anahtarı. Tarayıcı extension'ı (Xdebug helper) veya URL parametresiyle gönderilen key ile eşleşir. Genellikle VS Code için VSCODE veya PHPSTORM kullanılır.

3. VSCode Debug Ayarı (launch.json)

Proje ana dizininde .vscode klasörü oluşturun ve içine launch.json dosyasını şu şekilde ekleyin. Bu adım, Docker içindeki dosya yollarını Windows ile eşleştirir:

JSON

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug (Docker)",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}/html"
            }
        }
    ]
}

---

version: VS Code'nin anlayacağı json versiyonu

name: VS Code Debug panelinde görünecek isim

type: Debugger tipi

requst: iki seçenek var.

- "launch": VS Code'un kendisi bir PHP process'i başlatır (CLI için)

- "attach" veya burada kullanılan "launch" ile "Listen" modu:

VS Code Xdebug bağlantısını DINLER (en yaygın kullanım)

port: Xdebug'un bağlanacağı port numarası

pathMappings: Sunucudaki dosya yolu

    - "/var/www/html": "${workspaceRoot}/html": yerel bilgisayarınızdaki proje klasörü arasındaki eşleme

ignore: Debug sırasında bu yolların içindeki dosyaları yok say.

4. Tarayıcı Desteği: Xdebug Helper Eklentisi

Debug işlemini tarayıcı üzerinden kontrol etmek işleri çok kolaylaştırır.

1. Chrome için Xdebug Helper eklentisini kurun.

2. Eklenti ayarlarından IDE Key olarak VSCODE seçin.

3. Tarayıcınızın sağ üstündeki böcek simgesine tıklayıp "Debug" modunu aktif edin (simge yeşile döner).

Bu eklenti, tarayıcıya bir çerez ekleyerek PHP'ye "bu isteği durdur ve VSCode'a sinyal gönder" talimatı verir.

---

5. Nasıl Çalıştırılır?

1. Terminalde docker-compose up -d --build komutunu çalıştırın.

2. VSCode'da F5'e basarak "Listen for Xdebug" modunu başlatın (Alt bar turuncu olur).

3. Kodunuzun bir satırına breakpoint (kırmızı nokta) koyun.

4. Tarayıcıda http://localhost:8888/test.php adresini yenileyin. Tebrikler! Kodunuz VSCode üzerinde durdu.

---

Önemli İpuçları

• MySQL Bağlantısı: PHP kodunuzda host olarak localhost değil, db yazmalısınız.

• Veri Güvenliği: Docker konteynırlarını silseniz bile /mysql_data ve /html klasörleri sayesinde verileriniz Windows tarafında güvende kalır.

---

Bu rehber işinize yaradı mı? Sorularınızı yorumlarda sorabilirsiniz!