PhpStorm과 Xdebug로 PHP 디버깅하기

들어가며

PHP로 개발을 할 때 사용하는 디버깅 도구로는 Xdebug 가 있습니다.

 

브레이크 포인트를 설정하고 스텝 실행 및 각 스텝별로 변수에 담긴 값들을 확인할 수 있습니다

제가 처음 입사한 회사에서는 디버깅 도구를 사용하지 않았기 때문에, 확인이 필요한 곳에 var_dump, print_r 등으로 출력하면서 디버깅을 했었는데요, 그러다 이직 후에 xdebug 를 사용하면서 신세계를 경험했던 기억이 있습니다.
본 글에서는 PHP 개발에 있으면 큰 힘이 되는 xdebug 를 PhpStorm 에 연계하는 방법에 대해서 정리해보았습니다.

본문에서 사용된 예시 환경은 아래와 같습니다.

 

• macOS 12.1 ( Apple M1 chip )
• PHP8
• Xdebug3
• Slim framework : version 4
• Docker Engine : 20.10.11
• docker-compose : version 1.29.2

내용

1. 컨테이너 설정

먼저 도커와 docker-compose 를 사용하여 개발환경을 컨테이너화합니다.

docker-compose.yml

# docker-compose.yml sample
version: '3.7'

volumes:
    logs:
        driver: local

services:
    slim:
        container_name: slim-php
        build:
            context: ./docker
        environment:
            docker: "true"
        ports:
            - 8080:8080
        volumes:
            - .:/var/www
            - logs:/var/www/logs

Dockerfile

FROM php:8-alpine

RUN apk update && apk upgrade
RUN apk add --no-cache php8-pear php8-dev gcc musl-dev make

# Xdebug 설치 및 설정 추가
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && echo "[xdebug]" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && 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=9001" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.idekey=phpstorm" >> /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

WORKDIR /var/www

ENTRYPOINT php -S 0.0.0.0:8080 -t public

2. PhpStorm 설정

Docker 추가하기

Build, Execution, Deployment > Docker 를 선택 후 + 를 눌러 Docker 를 추가하고, Docker for Mac 을 선택한 후 APPLY 합니다.

PHP > Debug 설정하기

PHP > Debug 선택 후, Xdebug 항목에서, Dockerfile 에서 설정한 포트번호 (여기서는 9001) 을 입력하고 APPLY 합니다.

PHP > Servers 설정하기

PHP > Servers 선택 후, + 를 눌러 적당히 이름을 입력후, Host 는 localhost, Port 는 Dockerfile 에서 php 서버 실행 시 지정한 8080 을 입력합니다.

그리고 Use path mappings 를 체크 후, 현재 프로젝트의 디렉토리를 Dockerfile 에서 지정한 work directory 와 매핑해줍니다.

이걸로 Preference 관련 설정은 완료되었습니다. 다음은 디버깅 실행과 관련된 설정이 필요합니다.

Run/Debug Configurations 설정하기

메뉴에서 Run > Edit Configurations 를 누르면 아래와 같은 창이 나옵니다.

+ 를 눌러서 PHP Remote Debug 를 추가한 후, 적당한 이름을 입력해줍니다.

Filter debug connection by IDE key 를 체크해주고, Server 는 위 Servers 에서 추가했던 서버를 선택해줍니다.

IDE key 에는 Dockerfile 에서 설정해줬던 idekey 값 (여기서는 phpstorm) 을 입력하고 OK 를 누릅니다.

이로써, PhpStorm 설정도 완료되었습니다.

3. 실행하기

개발환경을 기동시킵니다.

$ docker-compose up -d --build

PhpStorm 에서 위에서 추가했던 디버깅을 선택해줍니다.

초록색 벌레를 누르면 네모상자가 빨갛게 변하면서 실행을 기다리는 상태가 됩니다.

Debug 창을 누르면 위와 같은 탭이 표시됩니다. 

디버깅을 하고 싶은 라인 왼쪽을 클릭하면 빨간색 동그라미가 표시되면서 브레이크포인트가 설정됩니다. (복수 선택 가능)

( *디버깅은 이 브레이크 포인트를 얼마나 적절한 곳에 두는가에 따라 그 결과가 달라지므로 많이 경험해 보는 것이 좋습니다. )

브라우저에서 localhost:8080 를 열면, 브레이크 포인트에서 멈추게 되고, Debug 탭에서 해당 포인트에서 확인 가능한 변수들의 값들을 확인할 수 있습니다.

디버깅 설정 및 확인 방법은 이상입니다.

추가) 스텝 실행 방법

1. Step Over

한줄을 실행합니다. 함수가 있어도 실행 후 다음으로 넘어갑니다.

(함수 내부로 들어가고 싶을 경우, 다음에서 설명하는 Step Into 를 현재 줄에서 실행해야 합니다. )

2. Step Into

함수 내부로 들어갑니다.

3. Force Step Into

설정에서 Step Into 에서 굳이 확인이 불필요한 getter 등은 스킵할 지를 설정할 수 있는데, Force Step Into 는 스킵하지 않고 모두 확인합니다.

4. Step Out

함수를 끝까지 실행시키고 호출시킨 곳으로 되돌아 갑니다.

5. Run to Cursor

다음 브레이크포인트까지 실행합니다. 복수의 브레이크포인트 설정 후, 브레이크 포인트 단위로 휙휙 넘어가고 싶을 때 유용합니다.

이상입니다.

마무리

이상으로, PhpStorm 으로 Xdebug 를 통해 PHP 를 디버깅하는 설정방법과 실행방법에 대해 정리해보았습니다.
쾌적한 PHP 개발에 도움되시기를 바랍니다.