Thursday, August 21, 2025Debugging PHP with Xdebug and VS Code on Docker

Keven Client A. Cataluña @LinkedIn

Tags

Docker PHP Xdebug Visual Studio Code

Previous postSetup PHP development environment with Docker

Next postHow to install Nginx

← Back to the posts

Introduction

This guide explains how to configure Xdebug with PHP inside Docker for efficient debugging, including setting up the Xdebug configuration, rebuilding containers, resolving installation issues, configuring launch.json, and verifying that debugging works correctly.

PHP 7.3PHP 8.1

Steps1. Create an Xdebug configuration file with the following settings

ext-xdebug.ini

    zend_extension=xdebug.so
xdebug.mode=develop,coverage,debug,profile
xdebug.idekey=docker
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
xdebug.discover_client_host=true

2. Install and configure Xdebug extension

Dockerfile

    RUN pecl install xdebug-3.3.2 && docker-php-ext-enable xdebug
COPY ext-xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

3. Rebuild all the containers (Use the --network host option to resolve the issue) Error

    ------
 > [3/4] RUN pecl install xdebug-3.3.2 && docker-php-ext-enable xdebug:
6.897 No releases available for package "pecl.php.net/xdebug"
6.897 install failed
------
Dockerfile:3
--------------------
   1 |     FROM php:8.1-fpm
   2 |     WORKDIR /usr/share/nginx/html/docker-php
   3 | >>> RUN pecl install xdebug-3.3.2 && docker-php-ext-enable xdebug
   4 |     COPY ext-xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini
   5 |
--------------------
ERROR: failed to solve: process "/bin/sh -c pecl install xdebug-3.3.2 && docker-php-ext-enable xdebug" did not complete successfully: exit code: 1

Solution

    docker build --no-cache --network host -t [IMAGE] .

4. Install the PHP Debug extension in Visual Studio Code 5. Configure Xdebug in Visual Studio Code

.vscode/launch.json

    {
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "log": false,
    "externalConsole": false,
    "pathMappings": {
        "/usr/share/nginx/html/docker-php": "${workspaceFolder}",
    },
}

6. Check if Xdebug is working correctly

Keven Client A. Cataluña @LinkedIn