Laravel + Xdebug in Docker: Debugging, Coverage & Profiling

Summary

Learn how to set up Laravel inside Docker with Amazon Linux 2023, configure Xdebug for debugging, enable VSCode integration, run PHPUnit tests with coverage, and fix common issues.

What You’ll Learn

✅ Set up Laravel in Docker (Amazon Linux 2023)
✅ Install & configure Xdebug
✅ Integrate Xdebug with VSCode
✅ Run PHPUnit with coverage
✅ Troubleshoot common issues

🚀 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.

🎯 Conclusion

Now you have Laravel running in Docker with Xdebug for:
✅ Step debugging in VSCode
✅ Running PHPUnit tests with coverage
✅ Profiling Laravel performance