DEV Community

Cover image for Debug Docker PHP Project on PHPStorm using Xdebug

Posted on

Debug Docker PHP Project on PHPStorm using Xdebug

My First Article

In this article I will share my debugging experience with Xdebug on PHP development environment in Docker, but before going any further, I assume you are familiar with Docker, Docker Compose, and using PHPStorm as your IDE.


This my structure code:
Image description

I put all of configuration for docker inside docker folder, but what conf we need for now is only :

  • nginx/nginx.conf
  • php/conf.d/php.ini
  • docker-compose.yml
  • Dockerfile

Below is all my configuration:


server {
    listen 80;
    server_name web;

    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    error_page 404 /index.php;
    root /var/www/public;
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param SERVER_NAME $server_name;
        fastcgi_param SERVER_NAME $host;
    location / {
        try_files $uri $uri/ /index.php?$query_string;
        gzip_static on;

Enter fullscreen mode Exit fullscreen mode


FROM php:8.1.0-fpm

ADD /usr/local/bin/

RUN apt-get update && apt-get install -y \
    git \
    curl \
    zip \
    nano \
    vim \

RUN chmod +x /usr/local/bin/install-php-extensions && \
    install-php-extensions gd xdebug pdo-mysql

RUN docker-php-ext-install pdo pdo_mysql

RUN php -r "copy('', 'composer-setup.php');"
RUN php composer-setup.php --install-dir=. --filename=composer
RUN mv composer /usr/local/bin/

COPY ../ /var/www/

WORKDIR /var/www

Enter fullscreen mode Exit fullscreen mode


version: '3.8'

            context: ./
            dockerfile: Dockerfile
        image: myapp/php
        container_name: myapp
        restart: always
        working_dir: /var/www/
            - ../:/var/www
            - ./php/conf.d/php.ini:/usr/local/etc/php/php.ini
            - /tmp/xdebug:/tmp/xdebug
        image: nginx:1.19-alpine
        container_name: mywebserver
        restart: always
            - 8000:80
            - ../:/var/www
            - ./nginx:/etc/nginx/conf.d

Enter fullscreen mode Exit fullscreen mode

You just copy default php.ini and add these line of xdebug conf, and remember your xdebug.idekey value


xdebug.idekey = docker

Enter fullscreen mode Exit fullscreen mode

note : host.docker.internal for linux

Let's debugging

I hope your container runs without any problems, then now we are going to configure PHPStorm.

  1. Here we want to configure our PHP docker interpreter. a. Go to `Preferences > PHP, add new interpreter, select new interpreter from Docker, vagrant, etc...

Image description
Image description
b. Create new Server.
Image description
Image description

c. After selecting an Interpreter, we are going to map our working project with container path, my working project path is $HOME/DOO/api docker and I will map into /var/www/, so change the Docker container value:
Image description

d. This the result :
Image description

  1. Xdebug configuration.
    a. Go to Preferences > PHP > Debug, set like this:
    Image description
    b. Go to Preferences > PHP > Debug > Dbgp Proxy, set like this (note: IDE Key must same with the value of xdebug.idekey on php.ini):

    Image description
    c. Go to Run > Edit Configurations..., create a new PHP Remote Debug configuration:
    Image description
    Image description
    d. Go to Run > Web Server Debug Validation, on Path to create validation script I point the value into my public path of project, and URL to validation script I point to my nginx docker host.
    Image description

    a. Set breakpoint, and turning on Start Listening for PHP Debug Connection
    Image description

Image description

b. Go to Run > Debug then select the configuration what we made earlier (PHP Remote Debug):
Image description

c. Go to your endpoint, and add query string with parameter XDEBUG_SESSION_START and the value is your IDE Key, then execute! :
Image description

Image description

Top comments (0)