Setup Xdebug for PHP in Docker for VS Code

Dmytro Tus

Full Stack Web developer

In this post I will show, how to add xdebug for existing project which in Docker container.

In my case there is a docker-compose.yml file

version: '3.9'

services:
### another scripts
# php
    php82-service:
        build:
            context: .
            dockerfile: ./docker/php/Dockerfile
        container_name: whoisdima-php
        ports:
            - "9117:9000"
        volumes:
            - ./:/var/www/project
            - ./docker/php/php_ini:/usr/local/etc/php/php_ini ## add this line for mount php.ini into docker ( when copypase paste in php_ini correct way )
### another scripts

In my project, as you can see there is an external Dockerfile

./docker/php/Dockerfile

This Dockerfile contain content which is similar to:

FROM php:8.2-fpm

RUN apt-get update && apt-get install -y zlib1g-dev g++ git libicu-dev zip libzip-dev zip \
    libpng-dev \
    libwebp-dev \
    libfreetype6-dev libjpeg62-turbo-dev\
    && docker-php-ext-install intl opcache pdo pdo_mysql \
    && pecl install apcu \
    && docker-php-ext-enable apcu \
    && docker-php-ext-configure zip \
    && docker-php-ext-install zip \
    && docker-php-ext-install exif \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-enable gd \
    && pecl install xdebug \                 <-------------------- add this line for xdebug
    && docker-php-ext-enable xdebug <-------------------- add this line for xdebug

Is the same directory as Dockerfile we need to add php.ini file. We need this file to enable some xdebug configurations.

// php.ini 

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = trigger <------ in some tutorials you will find value true here.
xdebug.client_host = host.docker.internal

I am using start_with_request = trigger, and not true, because when this value is set to true, the error while testing with PhpUnit tests will appear.

Then let's integrate xdebug into VsCode. For that we need to download the extension with name "PHP Debug"

Then click "add configuration" to the VSCode:

The content of the file launch.json is below:

{
   "version": "0.2.0",
    "configurations": [
        
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/project": "/Users/username/Documents/webdev/www/whoisdima" <------ this line is important, here we map our docker to local folder
            }
        }

}

I am using laravel and when we are running tests

php artisan test --coverage

We can use --coverage flag and we will see how many code is covered by our tests. 

To enable this feature we just need to add one line into php.ini

[xdebug]
xdebug.mode = debug,coverage <---- add coverage

That's all. Happy coding 😎