라라벨 개발 환경 구축 : Debugging with VSCode

디버깅은 소프트웨어 개발 과정에서 불가피한 부분으로, 코드의 오류를 신속하게 찾아내고 수정하는 데 큰 도움을 준다. 많은 개발자들이 사용하는 Visual Studio Code (VSCode)를 활용하여 라라벨 애플리케이션을 디버깅하는 방법 정리한다.

Xdebug 설치 및 활성화

Xdebug 설치 여부 확인 방법

php -v

PHP 8.3.1 (cli) (built: Dec 20 2023 12:44:38) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.1, Copyright (c) Zend Technologies
    with Xdebug v3.3.1, Copyright (c) 2002-2023, by Derick Rethans
    with Zend OPcache v8.3.1, Copyright (c), by Zend Technologies

⚠️ Xdebug와 PHP의 버전 호환성은 Xdebug 공식 페이지에서 확인가능하다.

Xdebug 설치

pecl install xdebug

Xdebug 활성화

Xdebug가 설치되었으면 현재 본인이 사용하고 있는 php에서 Xdebug를 활성화 해야 디버깅이 가능하다. 아래 명령을 실행하여 php.ini 파일의 위치를 확인하고 수정해야 한다.

php.ini 파일 위치 확인 방법

php --ini

Configuration File (php.ini) Path: /opt/homebrew/etc/php/8.3
Loaded Configuration File:         /opt/homebrew/etc/php/8.3/php.ini
Scan for additional .ini files in: /opt/homebrew/etc/php/8.3/conf.d
Additional .ini files parsed:      /opt/homebrew/etc/php/8.3/conf.d/ext-opcache.

2번째 줄 Loaded Configuration File 에 출력되는 php.ini 파일을 열어 아래 값을 추가한다.

zend_extension="xdebug.so"

;add xdebug configuration
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9000
xdebug.client_host=127.0.0.1
xdebug.log=xdebug.log

zend_extention : 값은 설치한 Xdebug 모듈의 경로(기본으로 xdebug.so 로 설정되어 있다. 만약, 경로를 찾지 못한다면 환경 변수를 확인한다.)
xdebug.mode : Xdebug의 모드를 설정한다. develop, coverage, debug, profile, trace 등 여러 모드를 지원한다.
xdebug.start_with_request : 요청이 있을 때 Xdebug를 자동으로 시작할지 여부를 설정한다. 이 값이 yes로 되어 있어야 외부에서 API를 통해 호출될 경우 디버깅을 할 수 있게 된다.
xdebug.client_port : Xdebug와 VSCode간의 디버깅 데이터를 주고 받을 때 사용되는 포트이다. 이 값은 VSCode 의 launch.json에 작성된 포트와 일치해야 한다.
xdebug.client_host : Xdebug와 VSCode간의 디버깅 데이터를 주고 받을 때 사용되는 호스트 주소이다. 이 값은 VSCode 의 launch.json에 작성된 호스트 주소와 일치해야 한다.
xdebug.log : Xdebug의 로깅 파일 출력 위치를 결정 한다.

vsCode 설정

PHP Debug 확장 설치

VSCode의 확장 프로그램 탭에서 “PHP Debug” 확장을 찾아 설치한다.

브레이크포인트 설정과 디버깅 실행

launch.json 작성

launch.json

디버깅을 시작하려면 launch.json 파일을 설정하여 디버깅 환경을 구성해야 한다. 이 파일은 VSCode의 디버깅 탭에서 최초로 디버깅을 실행할 경우 자동로 프로젝트의 .vscode 폴더 내에 생성된다. 만약 폴더가 없다면 직접 생성한 뒤 아래 내용을 추가한다.

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "hostname": "localhost"
    }
  ]
}