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.

Preparation

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:

nginx/nginx.conf



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

Dockerfile



FROM php:8.1.0-fpm

ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

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

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('https://getcomposer.org/installer', 'composer-setup.php');"
RUN php composer-setup.php --install-dir=. --filename=composer
RUN mv composer /usr/local/bin/

COPY ../ /var/www/

WORKDIR /var/www

EXPOSE 9000


Enter fullscreen mode Exit fullscreen mode

docker-compose.yml



version: '3.8'

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



Enter fullscreen mode Exit fullscreen mode

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



[Xdebug]

xdebug.mode=debug,trace
xdebug.client_host=docker.for.mac.host.internal
xdebug.client_port=9003
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

  2. EXECUTE!
    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

Taraaaaa!
Image description

Top comments (1)

Collapse
 
michael_ishmael_pl profile image
Michael Ishmael

Thank you! Thank you! Thank you! I've been struggling with this for hours until I found your post.