XDebug로 PHP 프로젝트 디버깅하기

XDebug는 PHP 개발에서 강력한 디버깅, 성능 분석, 코드 커버리지 측정 기능을 제공하는 도구입니다. ServBay 로컬 개발 환경에 XDebug를 통합해 사용하면, PHP 프로젝트의 개발 효율성과 코드 품질을 크게 향상시킬 수 있습니다. XDebug를 통해 코딩 중 중단점을 설정하거나 변수 값을 점검하고, 함수 호출 스택을 추적하거나 성능 병목 현상을 분석하는 등 문제를 신속하게 파악하고 해결할 수 있습니다.

XDebug 소개

XDebug는 PHP를 위해 설계된 확장 프로그램으로, 뛰어난 디버깅과 분석 기능을 제공합니다. XDebug는 원격 디버깅(일반적으로 DBGp 프로토콜 사용), 중단점 설정, 단계별 실행, 변수값 확인, 함수 호출 스택 추적, 스크립트 성능 분석(프로파일링), 코드 커버리지 리포트 생성을 지원합니다. 이를 통해 개발자는 코드가 수행되는 과정과 내부 상태를 심층적으로 파악하여 문제를 더욱 효율적으로 찾아낼 수 있습니다.

XDebug에는 여러 동작 모드가 있지만, debug 모드가 가장 널리 사용되며, 이는 인터랙티브 중단점 디버깅에 사용됩니다.

ServBay에서 XDebug 활성화 및 설정하기

ServBay는 지원하는 각 PHP 버전에 대해 XDebug 확장 모듈을 미리 포함하고 있습니다. 별도의 다운로드나 컴파일이 필요하지 않습니다.

XDebug 모듈 활성화: ServBay 앱 인터페이스를 엽니다. 언어-PHP로 이동해 XDebug를 사용하려는 PHP 버전을 찾으세요. 확장에서 xdebug 모듈을 찾아 상태가 "활성화됨"인지 확인합니다. 비활성 상태라면 클릭해서 활성화하세요. 활성화 후 PHP-FPM 서비스 재시작이 필요할 수 있습니다(ServBay가 자동으로 처리).
IDE 설정: 사용하는 IDE(예: PHPStorm 또는 VS Code)에서 XDebug 연결을 설정하세요. 일반적으로 포트 번호(ServBay UI XDebug 설정과 일치) 지정, 필요시 원격 경로 매핑(로컬 프로젝트 경로와 서버 경로가 다를 때, 로컬 ServBay에서는 보통 필요 없음)을 포함합니다.
IDE 설정 자세히 보기
특정 IDE(PHPStorm, VS Code 등)에서 XDebug를 어떻게 설정하는지 더 자세한 절차는 각 IDE 공식 문서나 ServBay 내장 XDebug 모듈 활성화 안내를 참고하세요.

실전 예시: ServBay에서 PHP 프로젝트 디버깅

아래의 간단한 예제 프로젝트로 ServBay에서 XDebug를 활용한 디버깅 과정을 설명합니다.

1. ServBay 사이트 세팅

먼저, 신규 웹사이트를 ServBay에 생성하여 예제 프로젝트를 배포하세요.

ServBay 웹사이트 루트 디렉토리 /Applications/ServBay/www/에 새로운 프로젝트 폴더(예: servbay-xdebug-app)를 만듭니다.
ServBay 앱을 열고 "사이트" 섹션으로 이동합니다.
새 사이트 추가를 클릭하고, 사이트 루트를 /Applications/ServBay/www/servbay-xdebug-app로 지정합니다.
로컬 도메인 예를 들어 servbay-xdebug-app.servbay.demo로 설정합니다.
원하는 PHP 버전을 선택하고 해당 버전의 XDebug가 앞서 안내한 방식으로 활성화·설정됐는지 확인합니다.
설정을 저장하면 ServBay가 자동으로 Caddy/Nginx를 구성하며 hosts 파일(또는 ServBay DNS 서비스)을 업데이트합니다.

2. 예제 프로젝트 구조 및 코드

/Applications/ServBay/www/servbay-xdebug-app/ 경로에 아래와 같은 파일/폴더를 생성하세요.

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

src/Calculator.php 파일 예시:

php

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // 이 줄에 중단점(breakpoint) 설정
        return $a + $b;
    }

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

index.php 파일 예시:

php

<?php
// Composer를 사용하는 경우 자동로더를 불러옵니다.
// Composer를 사용하지 않는다면 실제 환경에 맞게 로딩 방식을 수정하세요.
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Debugging Example:\n";

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

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

echo "Sum: " . $sum . "\n";
echo "Difference: " . $difference . "\n";

echo "Done.\n";
?>

참고: 위의 require __DIR__ . '/vendor/autoload.php';는 Composer 사용을 전제합니다. 단순 테스트라면 해당 라인을 삭제하고, use App\Calculator;대신 require __DIR__ . '/src/Calculator.php'; 로 변경하세요.

3. 중단점 설정

IDE(PHPStorm 등)에서 /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php 파일을 열고, add 메서드의 return $a + $b; 줄 번호 옆을 클릭해 중단점을 설정하세요.

4. 디버깅 세션 시작

IDE에서 XDebug 연결 대기(Listening) 기능을 활성화합니다. PHPStorm의 경우 상단 툴바에 있는 "PHP Debug 연결 대기 시작" 버튼(전화기 또는 벌레 아이콘)을 클릭하세요.
브라우저에서 ServBay 사이트의 index.php 파일에 접근: https://servbay-xdebug-app.servbay.demo/index.php.
만약 xdebug.start_with_request가 trigger로 설정된 경우, 브라우저 확장 프로그램이나 수동 방식으로 XDebug 트리거(예: https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1 URL로 접속)를 추가해야 합니다.

5. 디버깅 진행

브라우저에서 index.php 요청이 들어가고 XDebug 세션이 트리거되면, XDebug가 IDE에 자동으로 연결되어 설정한 중단점에서 코드 실행을 멈춥니다.
IDE가 디버깅 뷰로 전환되어 Calculator.php의 add 메서드 return 줄에서 코드가 멈춘 것을 볼 수 있습니다.

6. 변수 값 확인

IDE의 디버깅 창에서 현재 실행 중인 코드 줄, 호출 스택(Call Stack), 변수값(Variables) 등을 확인할 수 있습니다.
"Variables" 패널에서 현재 범위의 변수 값도 확인 가능하며, 예시로 $a는 5, $b는 3인 것을 볼 수 있습니다.

7. 단계별 실행

IDE에 제공되는 단계별 실행(Step Over: F8, Step Into: F7, Step Out: Shift+F8 등) 기능을 활용하세요.
- Step Over: 현재 줄을 실행하며, 해당 줄이 함수 호출이면 함수 내부로 들어가지 않고 다음 줄로 이동합니다.
- Step Into: 현재 줄이 함수 호출이면, 함수 내부 첫 줄로 이동해 실행을 이어갑니다.
- Step Out: 현재 함수 내 남은 코드를 실행 후, 함수를 벗어나 호출 지점으로 돌아갑니다.
단계별 실행을 통해 코드 흐름 및 변수 값 변화 과정을 한 줄씩 추적할 수 있습니다.

8. 계속 실행

IDE에서 "Resume Program" 버튼(일반적으로 초록색 재생 아이콘 또는 F9)을 클릭하면 다음 중단점까지 혹은 종료 시까지 코드 실행이 이어집니다.

9. 결과 출력 확인

코드가 완료되면 브라우저(또는 CLI 디버깅의 경우 터미널)에서 출력을 확인하세요. 예시 결과는 아래와 같습니다.
text
```
Debugging Example:
Sum: 8
Difference: 2
Done.
```
1
2
3
4

참고사항

방화벽: 운영 체제의 방화벽이 IDE가 사용하는 디버그 포트(기본 9003) 접근을 차단하지 않도록 하세요.
포트 충돌: XDebug 포트가 다른 앱에서 이미 사용 중인 경우 충돌이 발생할 수 있으니 확인하세요.
성능 영향: xdebug.mode=debug이며 xdebug.start_with_request=yes로 설정된 경우, 모든 PHP 요청에 대해 디버깅이 시도되어 사이트 성능 저하가 뚜렷합니다. 필요 없을 땐 XDebug를 비활성화하거나 xdebug.start_with_request를 trigger로 변경하세요.
CLI 스크립트 디버깅: XDebug는 PHP CLI 스크립트 디버깅에도 사용 가능합니다. 환경 변수 세팅이나 특정 파라미터 사용 등, 자세한 트리거 방법은 XDebug 공식문서를 참고하세요.
IDE 버전 및 설정: IDE의 버전과 옵션, 설정 화면이 다소 다를 수 있으니 공식 문서를 참고해 세팅하세요.

자주 묻는 질문 (FAQ)

Q: IDE가 XDebug에 연결되지 않아요. 어떻게 해야 하나요?

A: 아래 사항을 점검하세요.

ServBay에서 해당 PHP 버전에 XDebug 모듈이 활성화되어 있는지 확인.
php.ini의 xdebug.mode, xdebug.client_host, xdebug.client_port가 올바르게 설정되었는지, 그리고 IDE의 리스닝 설정과 일치하는지 확인.
xdebug.start_with_request = trigger 사용하는 경우, 트리거(GE/POST 파라미터, 쿠키, 헤더 등)가 올바르게 추가됐는지 확인.
OS 방화벽에서 XDebug 포트 트래픽이 차단되지 않았는지 확인.
IDE가 해당 포트를 리스닝 중인지 다시 확인.

Q: XDebug를 켜면 사이트가 너무 느려져요.

A: 대개 xdebug.start_with_request를 yes로 설정하면 발생합니다. 이 방식은 모든 PHP 요청에서 항상 디버깅을 시도해, 성능 저하가 큽니다. trigger로 변경하여, 꼭 필요할 때만 수동으로 디버깅을 시작하세요.

Q: XDebug로 AJAX 요청도 디버깅할 수 있나요?

A: 네, 가능합니다. 일반 HTTP 요청처럼, AJAX 요청에도 XDebug 트리거(보통 쿠키나 헤더 추가)를 포함시키면 동일하게 디버깅할 수 있습니다.

Q: ServBay의 XDebug는 PHPStorm 외에 VS Code 같은 IDE도 지원하나요?

A: 네. ServBay의 XDebug는 표준 PHP 확장으로, DBGp 디버깅 프로토콜을 지원하는 모든 IDE·에디터(예: VS Code(php debug 익스텐션과 함께), NetBeans, Eclipse 등)에서 사용할 수 있습니다. 주요 차이는 IDE에서 리스닝 포트 설정 등 환경 설정 부분에 있습니다.

결론

ServBay가 제공하는 XDebug 통합 환경을 활용하면, 개발자는 로컬에서 PHP 프로젝트를 손쉽게 효율적으로 디버깅할 수 있습니다. 중단점, 변수 검사, 단계별 실행 등 핵심 디버깅 기술을 익혀 문제 해결 능력과 코드 품질을 대폭 향상시키세요. ServBay의 편리한 환경 관리와 결합할 때, XDebug는 PHP 개발 워크플로우의 핵심 도우미가 됩니다. 지금 바로 ServBay에서 XDebug 디버깅을 시작해 더욱 유연하고 생산적인 PHP 개발을 경험해보세요!

XDebug로 PHP 프로젝트 디버깅하기 ​

XDebug 소개 ​

ServBay에서 XDebug 활성화 및 설정하기 ​

실전 예시: ServBay에서 PHP 프로젝트 디버깅 ​

1. ServBay 사이트 세팅 ​

2. 예제 프로젝트 구조 및 코드 ​

3. 중단점 설정 ​

4. 디버깅 세션 시작 ​

5. 디버깅 진행 ​

6. 변수 값 확인 ​

7. 단계별 실행 ​

8. 계속 실행 ​

9. 결과 출력 확인 ​

참고사항 ​

자주 묻는 질문 (FAQ) ​

결론 ​