Setup Xdebug in PhpStorm with Docker

setup Xdebug in PhpStorm with Docker PHP

» Assuming we have project layout consisting of multiple Docker containers, each serving distinct purposes, the following `Dockerfile` placed within the docker directory sets up a PHP environment with Xdebug:

project-root/
│
├── docker/
│   ├── mysql/
│   │   ├── Dockerfile
│   │   └── my.cnf
│   ├── nginx/
│   │   ├── Dockerfile
│   │   ├── nginx.conf
│   │   └── sites-available/
│   │       ├── default
│   │       ├── cdn.flagtick.com
│   │       ├── api.flagtick.com
│   │       ├── dashboard.flagtick.com
│   │       ├── listener.flagtick.com
│   │       └── resource.flagtick.com
│   ├── php/
│   │   ├── Dockerfile
│   │   └── php.ini
│   ├── phpmyadmin/
│   │   ├── Dockerfile
│   │   └── config.inc.php
│   └── docker-compose.yml
│
├── cdn/
│   ├── Dockerfile
│   └── cdn-config/
│       └── cdn.flagtick.com.conf
│
├── api/
│   ├── Dockerfile
│   └── api-config/
│       └── api.flagtick.com.conf
│
├── dashboard/
│   ├── Dockerfile
│   └── dashboard-config/
│       └── dashboard.flagtick.com.conf
│
├── listener/
│   ├── Dockerfile
│   └── listener-config/
│       └── listener.flagtick.com.conf
│
└── resource/
    ├── Dockerfile
    └── resource-config/
        └── resource.flagtick.com.conf

» In the path `docker/php/Dockerfile`, include the script provided below.

# install xdebug
RUN pecl install xdebug-3.1.5 \ 
    && docker-php-ext-enable xdebug 
COPY ./xdebug.ini "${PHP_INI_DIR}/conf.d"

» Create `xdebug.ini` file in the same folder as the Dockerfile.

xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal
xdebug.discover_client_host=1
xdebug.idekey=PHPSTORM

» Navigate to File » Settings » Debug, and modify the settings as shown in the screenshot below:

» Add the port mapping for port 9000 within the `nginx` service block in your `docker-compose.yml` file. Since the NGINX container serves as a reverse proxy for your PHP application container, it needs to forward traffic on port 9000 to the PHP container for debugging purposes.

services:
  nginx:
    container_name: "flagtick-nginx"
    build: ./docker/nginx
    ports:
      - "80:80"
      - "443:443"
      - "9000:9000"  # Add this line for Xdebug debugging
    depends_on:
      - cs_http_php7
    volumes:
      - "./docker/nginx/timeout.conf:/etc/nginx/conf.d/timeout.conf"
      - "./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf"
    networks:
      - web_server

» Enable `xdebug.mode=debug` in your `php.ini` configuration for Xdebug to work properly with the Xdebug Helper Chrome extension from your local machine.

php -m -c

Note: Refer to this link for more information on Xdebug and how to set it up. Or you can also check from the `Exec` tab in Containers in Docker Desktop.

» After installing Xdebug Helper in Chrome, right-click on the Xdebug icon and select `Options`. The Xdebug Helper settings will open. Choose `PhpStorm` as the IDE key, then click the Save button.

» If you have already created debug session previously, navigate to File » Settings » PHP » Servers. If you see that the domain is already registered for debugging and you want to re-establish it, remove the existing entry.