Laravel에서 Sail 사용시 Xdebug 설정

Seong-Am Kim

5 min readAug 5, 2024

라라벨에서 Sail 사용시 디버깅 설정하는데 몇가지 애로 사항이 있는데 이와 관련된 정리된 한국어 글이 없어 정리하고자 한다.

Mac 환경 위주로 정리했는데 다른 운영체제에서도 기본 적인 설정 개념은 동일하다.

PHP가 기본적으로 설치되어 있다고 가정한다.

1. Xdebug 설치

Laravel은 PHP 프레임워크이므로 이와 관련된 유명한 디버거인 Xdebug를 아래 명령어를 통해 설치한다.

pecl install xdebug

Linux와 Mac 환경에서만 위의 명령어로 설치하고 그 밖에 다른 운영체제는 Xdebug 공식 홈페이지를 참고하여 설치한다.

2. PHP.ini 설정 변경

아래 명령어로 php.ini 파일의 위치를 확인한다.

php -i | grep php.ini

php.ini 파일을 열어 아래 내용을 추가한다. Sail은 기본적으로 도커를 사용하기 때문에 이를 PHP에게 알려줘야 한다.

[XDebug]
zend_extension=xdebug
xdebug.start_with_request = yes
xdebug.show_local_vars = on
xdebug.mode = debug
xdebug.discover_client_host = true
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

3. Laravel 프로젝트 .env 변경

라라벨 프로젝트의 .env 환경변수에 아래 내용을 추가한다.

SAIL_XDEBUG_MODE=develop,debug,coverage

4. docker-compose.yaml 내용 추가

라라벨 프로젝트의 docker-compose.yaml에 아래 내용을 추가한다.

services:
  laravel.test:
    build:
      args:
        XDEBUG: '${APP_DEBUG:-false}' # 추가
        XDEBUG_PORT: '${SAIL_XDEBUG_PORT:-9003}' # 추가
    environment:
       LARAVEL_SAIL: 1 # 추가

5. IDE 디버거 설정

VSCode의 경우

php 디버깅을 위한 아래 확장 프로그램을 설치한다.

PHP Debug - Visual Studio Marketplace

Extension for Visual Studio Code - Debug support for PHP with Xdebug

marketplace.visualstudio.com

프로젝트에 .vscode/lauch.json 아래 내용의 파일을 생성한다.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
        }
    ]
}