Laravel + Xdebug in Docker: Debugging, Coverage & Profiling

Getting Xdebug working inside Docker shouldn’t take hours. But it usually does, because every guide assumes a different base image and half the config options are wrong for your setup.

This is the setup that works with Amazon Linux 2023, PHP 8.2, and VSCode. Step debugging, code coverage, profiling. The full stack.

Step 1: Create the Dockerfile**

This Dockerfile:

Uses Amazon Linux 2023
Installs PHP 8.2, Composer, and Laravel dependencies
Installs Xdebug for debugging & profiling
Exposes Laravel (80) & Xdebug (9003) ports

FROM public.ecr.aws/amazonlinux/amazonlinux:2023
USER root

# Install PHP 8.2 & essential tools
RUN dnf install -y php8.2 php-pear php8.2-devel gcc make autoconf wget git unzip nginx

# Install PHP extensions
RUN dnf install -y php-{cli,pdo,common,curl,mbstring,gd,mysqlnd,gettext,bcmath,json,xml,fpm,intl}

# Install Composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# Install & configure Xdebug
RUN pecl install xdebug
RUN echo "zend_extension=$(find /usr/lib64/php/modules/ -name xdebug.so)" > /etc/php.d/15-xdebug.ini && \
    echo "xdebug.mode=debug,develop,coverage,profile" >> /etc/php.d/15-xdebug.ini && \
    echo "xdebug.client_host=host.docker.internal" >> /etc/php.d/15-xdebug.ini && \
    echo "xdebug.start_with_request=trigger" >> /etc/php.d/15-xdebug.ini && \
    echo "xdebug.client_port=9003" >> /etc/php.d/15-xdebug.ini

WORKDIR /var/www/html
EXPOSE 80 9003
CMD ["/bin/bash"]

Step 2: Build & Run Docker**

1. Build the Image

docker build --no-cache -t laravel-xdebug .

2. Run the Container

docker run -d -p 80:80 -p 9003:9003 --name laravel-xdebug laravel-xdebug

3. Verify Xdebug

docker exec -it laravel-xdebug bash
php -m | grep xdebug

Step 3: Install Laravel in Docker**

Inside the container:

cd /var/www/html
composer create-project --prefer-dist laravel/laravel .
php artisan serve --host=0.0.0.0 --port=80

Visit: http://localhost:80

Step 4: Configure VSCode for Debugging**

Install PHP Debug extension in VSCode.
Create .vscode/launch.json in your Laravel project:

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

Start debugging in VSCode (Run > Start Debugging).
Set breakpoints in Laravel controllers/routes.

Step 5: Debugging & PHPUnit with Coverage**

Trigger Debugging

**Web Requests:
http://localhost:80/home?XDEBUG_SESSION_START=1
**CLI (Artisan Commands):
```
XDEBUG_SESSION=1 php artisan migrate
```

**PHPUnit Tests:

XDEBUG_SESSION=1 php artisan test --filter=MyTestClass

Run PHPUnit with Coverage

php artisan test --coverage-text
php artisan test --coverage-html coverage-report/

Step 6: Fix Xdebug Connection Issues**

If you see:

Xdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003

Try these steps:

1️⃣ **Verify Xdebug is installed:

php -m | grep xdebug

2️⃣ **Check Xdebug config:

php -i | grep xdebug

3️⃣ **Expose Port 9003:

docker run -d -p 80:80 -p 9003:9003 ...

4️⃣ **Use your host’s IP instead of host.docker.internal:

ip route | awk '/default/ { print $3 }'

Update:

xdebug.client_host=YOUR_HOST_IP

5️⃣ **Check if Xdebug is listening:

netstat -an | grep 9003

6️⃣ **Manually trigger Xdebug:
Append ?XDEBUG_SESSION_START=1 to URLs or use XDEBUG_SESSION=1 in CLI.

That’s it

Step debugging, coverage reports, and profiling in one Docker setup. The part that trips most people up is host.docker.internal not resolving. If that’s you, step 6 has the fix.