ServBay에서 Xdebug 모듈 활성화 및 설정 방법

ServBay는 강력한 로컬 웹 개발 환경으로, PHP 개발자들을 위해 Xdebug 디버깅 및 분석 도구를 기본 통합 제공합니다. Xdebug를 활성화하면 PHP 애플리케이션 개발 효율을 크게 높일 수 있으며, 코드 디버깅, 성능 분석, 코드 커버리지 측정도 쉽게 할 수 있습니다. 이 글에서는 ServBay에서 Xdebug를 활성화 및 설정하는 방법과, 주요 통합 개발 환경(IDE)에서 Xdebug를 연동하는 법을 상세히 안내합니다.

Xdebug 모듈 개요

Xdebug는 PHP 코드를 위한 디버깅과 분석에 특화된 강력한 PHP 확장 모듈입니다. ServBay에서는 Xdebug가 미리 통합되어 있어 컴파일 및 직접 설치 과정 없이 간편하게 활성화하고 설정할 수 있습니다.

Xdebug의 주요 기능

브레이크포인트 디버깅: 코드의 특정 라인에 중단점을 설정할 수 있으며, 실행이 중단된 상태에서 변수, 호출 스택 등을 세밀하게 살펴보며 한 줄씩 코드를 실행할 수 있습니다.
스텝 실행: 한 줄씩 실행(Step Over), 함수 진입(Step Into), 함수 탈출(Step Out) 등 각 단계별로 코드 흐름을 추적할 수 있습니다.
변수 모니터링: 디버깅 중 로컬/글로벌 변수의 값을 실시간으로 조회 가능합니다.
스택 트레이스: 오류나 예외 발생 시 상세한 함수 호출 스택 정보를 제공해 문제의 원인을 신속히 찾을 수 있습니다.
프로파일링: 코드 실행 성능 보고서를 생성하여 병목 구간을 파악할 수 있습니다.
코드 커버리지 측정: 테스트가 실제로 코드의 어느 부분을 실행하는지 비율로 제공해, 테스트의 효과성을 평가할 수 있습니다.

ServBay 기본 내장 Xdebug 버전 및 포트 매핑

ServBay는 PHP 버전별로 알맞은 Xdebug 모듈을 사전 설치해둡니다. 주의할 점은, 각 PHP 버전에 따라 Xdebug가 사용하는 리스닝 포트가 다르고, PHP 버전과 연동된다는 점입니다. 이 점은 IDE에서 디버거 설정 시 매우 중요합니다.

PHP 버전	내장 Xdebug 버전	기본 Xdebug 포트
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

포트 규칙

Xdebug의 기본 리스닝 포트는 39000 + PHP 소버전 규칙을 따릅니다. 예를 들어, PHP 8.3의 포트는 39000 + 83 = 39083, PHP 7.4의 포트는 39000 + 74 = 39074가 됩니다. 이 규칙을 알면 각 PHP 버전별 Xdebug 포트를 쉽게 확인할 수 있습니다.

Xdebug 모듈 활성화 방법

ServBay에서는 Xdebug 모듈 활성화가 매우 쉽습니다. ServBay의 그래픽 사용자 인터페이스(GUI)를 통한 활성화를 권장하며, 수동 설정도 가능합니다.

ServBay GUI를 통한 Xdebug 활성화

가장 쉽고 빠른 방법입니다.

ServBay 애플리케이션 인터페이스를 실행합니다.
좌측 네비게이션바에서 언어(Languages)를 선택합니다.
PHP 섹션을 펼치고, Xdebug를 활성화할 PHP 버전을 찾습니다. 예: PHP 8.3.
해당 버전 우측의 확장 버튼을 클릭합니다.
팝업된 확장 목록에서 Xdebug 모듈을 찾습니다.
Xdebug 모듈 좌측 토글 스위치를 켜서 활성화합니다.
필요한 경우 매개변수를 수정합니다.
인터페이스 하단의 저장 버튼을 클릭합니다.
ServBay가 자동으로 PHP 프로세스를 재시작하여 모듈을 적용합니다.

설명: 확장 대화창에서 Xdebug 활성화 예시

Xdebug 모듈이 정상적으로 로드됐는지 확인하기

가장 확실한 방법은 phpinfo() 함수를 통해 PHP 설정 정보를 직접 확인하는 것입니다.

ServBay 사이트 루트 디렉터리(기본값 /Applications/ServBay/www)에 PHP 파일을 생성합니다. 예: phpinfo.php.
phpinfo.php 파일에 다음 코드를 입력합니다:
php
```
<?php
phpinfo();
?>
```
1
2
3
브라우저에서 해당 파일에 접근합니다. 예: https://servbay.demo/phpinfo.php (여기서 servbay.demo는 ServBay에 설정한 사이트 도메인으로 바꿔주세요).
출력된 phpinfo 페이지에서 "Xdebug"를 검색합니다. Xdebug가 정상적으로 적용됐다면 별도의 "Xdebug" 설정 블록과 버전·설정값이 출력됩니다.

설명: phpinfo 출력에서 Xdebug 설정 위치 확인 예시

IDE에서 Xdebug 디버거 설정하기

Xdebug 활성화 이후, 본격적인 브레이크포인트 디버깅을 위해 IDE에서 PHP 인터프리터·디버거·서버 매핑 설정이 추가로 필요합니다. 아래 예시는 PHPStorm과 Visual Studio Code(VS Code)로 설명합니다.

PHPStorm에서 Xdebug 설정하기

PHPStorm은 Xdebug 지원이 매우 우수합니다.

PHPStorm 설정 열기: PHPStorm을 실행한 뒤, 메뉴에서 File -> Settings(Windows/Linux) 또는 PHPStorm -> Preferences(macOS)을 엽니다.
PHP CLI 인터프리터 등록:
- Languages & Frameworks -> PHP로 이동합니다.
- CLI Interpreter 항목에서 우측의 ... 버튼을 클릭합니다.
- 팝업 창에서 +를 눌러 새 로컬 인터프리터를 추가합니다.
- ServBay의 PHP 버전에 맞는 CLI 실행 파일 경로를 지정합니다. 예: /Applications/ServBay/package/php/8.3/8.3.7/bin/php (설치 상태에 따라 경로가 다를 수 있으므로 실제 경로를 확인해 주세요).
- PHPStorm이 자동으로 PHP 버전·확장 정보를 감지하며, Xdebug 포함 여부도 표시됩니다.
- OK를 클릭해 저장합니다. 설명: PHPStorm에서 ServBay PHP CLI 등록 화면
Xdebug 디버깅 파라미터 설정:
- Languages & Frameworks -> PHP -> Debug로 이동합니다.
- Xdebug 부분에서 Debug Port에, ServBay에서 활성화한 PHP 버전에 맞는 Xdebug 포트(예: PHP 8.3은 39083)를 입력합니다. 반드시 xdebug.client_port와 동일해야 합니다.
- Can accept external connections에 체크합니다.
- Apply 후 OK로 저장합니다. 설명: PHPStorm에서 Xdebug 포트 지정 화면
PHP 웹 서버 매핑 설정:
- Languages & Frameworks -> PHP -> Servers로 이동합니다.
- 우측의 + 버튼으로 새 서버를 추가합니다.
- 서버 이름 입력(예: ServBay Localhost)
- Host는 ServBay 내 도메인(예: servbay.demo)으로 등록합니다.
- Port는 사이트 사용 포트, 일반적으로 443(HTTPS) 또는 80(HTTP)입니다.
- Debugger는 Xdebug 선택.
- Use path mappings에 체크하세요.
- 로컬 프로젝트 경로(Absolute path to local source)와 서버 내 경로(Absolute path on the server)의 매핑을 입력합니다. 예를 들어 /Applications/ServBay/www/myproject경로와 웹의 루트(/)를 매핑합니다. 도메인 혹은 하위 도메인/하위 디렉터리 구조에 따라 적절히 조정하세요. 올바른 매핑이 Xdebug 정상 동작에 필수입니다.
- OK로 저장합니다. 설명: PHPStorm에서 서버 및 경로 매핑 설정 화면
디버그 세션 시작:
- PHPStorm에서 디버깅할 PHP 파일을 엽니다.
- 코드 라인 번호 왼쪽 여백 클릭으로 브레이크포인트(빨간 점)를 설정합니다.
- 툴바의 Start Listening for PHP Debug Connections(노란 벌레 아이콘) 버튼을 클릭합니다. 아이콘이 초록색으로 변경되면 정상적으로 Xdebug 연결 대기 상태입니다.
- 웹 브라우저에서 PHP 앱을 실행(예: https://servbay.demo/index.php).
- 설정이 올바르면 Xdebug가 자동으로 PHPStorm에 연결되어, 브레이크포인트에서 실행이 멈춥니다. 설명: PHPStorm의 Xdebug 리스닝 실행 화면

Visual Studio Code(VS Code)에서 Xdebug 설정하기

VS Code도 확장 설치로 Xdebug 디버깅을 효과적으로 지원합니다.

PHP Debug 확장 설치:
- VS Code를 실행합니다.
- 좌측 확장 탭(Ctrl+Shift+X 또는 Cmd+Shift+X)을 엽니다.
- "PHP Debug" 검색 후 Felix Becker의 확장 설치.

launch.json 설정:

PHP 프로젝트 폴더를 엽니다.
실행 및 디버깅 탭(Ctrl+Shift+D 또는 Cmd+Shift+D)으로 이동합니다.
상단 톱니바퀴 아이콘을 눌러 "PHP"를 선택하세요. 그러면 .vscode/launch.json 파일이 생성됩니다.
launch.json에서 "Listen for Xdebug" 구성의 port가 ServBay에서 사용하는 Xdebug 포트(예: PHP 8.3은 39083)와 일치하는지 확인하세요.

경로 매핑(Path Mapping) 설정: VS Code에서 Xdebug 정상 디버깅을 위해 pathMappings가 매우 중요합니다. ServBay 서버상의 경로와 로컬 프로젝트 경로를 올바르게 매핑 해야합니다.

json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 39083, // PHP 버전에 따라 포트 수정
            "pathMappings": {
                // ServBay 웹 루트의 프로젝트 경로와 로컬 파일시스템 경로 연결
                // 예: /Applications/ServBay/www/myproject 프로젝트가 https://servbay.demo/로 접근된다면
                // 서버 '/'는 로컬 프로젝트 루트와 같음
                "/": "${workspaceRoot}"
                // /Applications/ServBay/www/myproject에 있지만 https://myproject.servbay.demo/로 접근해도
                // 마찬가지로 '/' 매핑 충분
                // "/": "${workspaceRoot}" // 동일 적용 가능
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 39083 // PHP 버전에 따라 포트 수정
        }
    ]
}

프로젝트 구조와 ServBay 사이트 설정에 맞게 pathMappings를 조정하세요. ${workspaceRoot}는 일반적으로 VS Code에서 연 프로젝트 루트 폴더를 의미합니다.

디버깅 세션 시작:
- VS Code에서 PHP 프로젝트 파일을 엽니다.
- 코드 라인 번호 옆 클릭으로 브레이크포인트(빨간 점)를 추가합니다.
- 실행/디버깅 뷰(Ctrl+Shift+D 또는 Cmd+Shift+D)로 이동합니다.
- 상단 디버그 설정 드롭다운에서 "Listen for Xdebug"를 선택합니다.
- 녹색 디버그 시작 버튼을 클릭합니다. VS Code 상태바가 주황색으로 바뀌면 정상 연결 대기 상태입니다.
- 웹 브라우저에서 PHP 앱을 접속하면, 설정이 맞을 시 VS Code에 Xdebug가 연결되어 브레이크포인트에서 멈춥니다.

자주 묻는 질문 (FAQ)

Q: phpinfo()에서 Xdebug 모듈이 안 보여요.
- A: ServBay GUI에서 Xdebug를 켰는지 혹은 xdebug.ini 수동 설정 시 정상 활성화됐는지 확인하세요.
- 해당 PHP 서비스(버전)를 재시작 해주세요.
- xdebug.ini 경로 및 zend_extension = xdebug.so이 주석 없이 적용됐는지 점검하세요.
- ServBay 로그(/Applications/ServBay/logs/php/<version>/error.log)에서 Xdebug 로딩 에러 유무를 살펴보세요.
Q: IDE에서 브레이크포인트를 걸었는데 실행이 멈추지 않아요.
- A: IDE가 실제로 Xdebug 연결을 감지/리스닝 중인지 확인하세요(PHPStorm 벌레모양이 초록, VS Code가 주황색).
- IDE에서 설정된 Xdebug 포트가 ServBay의 xdebug.client_port 및 PHP버전별 포트와 같은지 확인하세요.
- **경로 매핑(Path Mapping)**이 올바른지 반드시 점검하세요. 서버 파일 경로와 로컬 프로젝트 파일이 매칭되어야 합니다. 경로 매핑 실수는 대부분의 설정 오류 원인입니다.
- 방화벽에서 IDE의 Xdebug 포트(기본 390xx 대역)를 막고 있지 않은지 확인하세요.
- 만약 xdebug.ini에서 xdebug.start_with_request=trigger를 사용한다면, 브라우저에 Xdebug Helper 확장 혹은 주소창에 ?XDEBUG_TRIGGER=1 파라미터 등 트리거 처리를 꼭 하세요.
Q: Xdebug가 일정 시간 후 연결이 끊깁니다.
- A: xdebug.ini에 설정된 xdebug.remote_autostart 또는 xdebug.start_with_request 값이 항상 yes라면 요청마다 디버깅이 시도되어 불필요하게 종료될 수 있습니다. 가능하면 trigger 모드 사용을 권장합니다.
- IDE의 시간제한(타임아웃) 설정도 확인하세요.

결론

ServBay는 Xdebug를 사전 통합 및 간편한 관리 방식으로 제공함으로써, PHP 개발자가 손쉽게 디버깅 환경을 구축하도록 돕습니다. GUI를 통한 직관적 설정은 물론, 수동 파일 편집 방식도 지원하여 다양한 환경에 적응할 수 있습니다. PHPStorm, VS Code 등 주요 IDE의 강력한 디버깅 기능과 연계하면 코드 수정, 성능 분석, 품질 관리까지 한층 효율적으로 진행할 수 있습니다. ServBay와 Xdebug를 자유자재로 활용하는 역량은 여러분의 로컬 PHP 개발 워크플로우에서 큰 경쟁력이 될 것입니다.

ServBay에서 Xdebug 모듈 활성화 및 설정 방법 ​

Xdebug 모듈 개요 ​

Xdebug의 주요 기능 ​

ServBay 기본 내장 Xdebug 버전 및 포트 매핑 ​

Xdebug 모듈 활성화 방법 ​

ServBay GUI를 통한 Xdebug 활성화 ​

Xdebug 모듈이 정상적으로 로드됐는지 확인하기 ​

IDE에서 Xdebug 디버거 설정하기 ​

PHPStorm에서 Xdebug 설정하기 ​

Visual Studio Code(VS Code)에서 Xdebug 설정하기 ​

자주 묻는 질문 (FAQ) ​

결론 ​