PHP 開發環境配置指南：Eclipse PDT + Xdebug/Zend Debugger 完整設置

PHP IDE 開發環境配置是提升開發效率的關鍵。本文記錄 Eclipse PDT 整合 Xdebug/Zend Debugger 的完整步驟，含常見坑點與替代方案推薦。

現代替代方案優先推薦

Eclipse PDT + Xdebug 配置 (歷史參考)

1. 安裝 Xdebug

# Ubuntu/Debian
sudo apt install php-xdebug

# Windows (XAMPP)
# 1. 下載對應 PHP 版本、TS/NT、VC 版本的 php_xdebug.dll
# 2. 放入 php/ext/
# 3. php.ini 加入:
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=VSCODE

2. Eclipse PDT 設置

1. 安裝 PDT：Eclipse Marketplace 搜尋 "PHP Development Tools"
2. 配置 PHP Executable：Window → Preferences → PHP → PHP Executables → Add
   • Name: PHP 8.2 (Xdebug)
   • Path: /usr/bin/php (或 XAMPP php.exe)
   • Debugger: Xdebug
3. 配置 Debug 配置：Run → Debug Configurations → PHP Web Application
   • Server: 預設或新增 (Base URL: https://localhost)
   • File: 專案入口檔
   • Debugger: Xdebug

3. 常見問題排查

VS Code + PHP Debug 現代配置 (推薦)

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "hostname": "0.0.0.0",
            "log": true
        },
        {
            "name": "Launch Built-in Server",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-dxdebug.mode=debug",
                "-dxdebug.start_with_request=yes",
                "-S", "localhost:8000",
                "-t", "${workspaceFolder}/public"
            ],
            "port": 9003
        }
    ]
}

Docker 環境 Xdebug 設定

# Dockerfile
FROM php:8.2-fpm
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

# php.ini
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=VSCODE
xdebug.log=/var/log/xdebug.log

# docker-compose.yml
services:
  php:
    build: .
    environment:
      XDEBUG_CONFIG: "client_host=host.docker.internal client_port=9003"
    extra_hosts:
      - "host.docker.internal:host-gateway"

Zend Debugger (舊版專案維護)

僅用於極舊專案 (PHP 5.2-5.6) 維護，現代專案請遷移至 Xdebug 3。

# php.ini (Windows XAMPP 1.6.8 範例)
zend_extension_ts="C:\xampp\php\ext\ZendDebugger.dll"
zend_debugger.allow_hosts=127.0.0.1,192.168.1.0/24
zend_debugger.expose_remotely=always

開發環境最佳實務清單

• ✅ 統一團隊 PHP 版本 (Docker/DevContainer)
• ✅ 程式碼風格檢查 (PHP_CodeSniffer + PHP CS Fixer)
• ✅ 靜態分析 (PHPStan Level 5+ / Psalm)
• ✅ 單元測試 (Pest / PHPUnit)
• ✅ 自動完成/類型提示 (Intelephense / PhpStorm)
• ✅ 零配置調試 (Xdebug 3 + VS Code/PhpStorm)

工具服務於開發流程，而非反之。選擇適合團隊技術棧、專案規模、維護週期的工具鏈，比追求「最強 IDE」更重要。