Yii3 + xDebug not working

Yii 3.0
1

Is it possible that the docker environment provided in application GitHub - yiisoft/app: Yii3 web application template · GitHub does not allow me to use debugging in PhpStorm? (I am running it on MacOs via Docker Desktop if it is important)

Yii2 worked well with following configuration:

Dockerfile:
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug2.ini

xdebug.ini:

;zend_extension=xdebug.so
xdebug.mode=develop,debug,coverage
xdebug.start_with_request=yes
;;; if you are on macOS, use host.docker.internal to identify the host machine, due to a network limitation on mac (https://docs.docker.com/docker-for-mac/networking/#port-mapping)
xdebug.client_host=host.docker.internal
;;; avoid standard port (9000) conflicts using 9005 port
xdebug.client_port=9003
xdebug.idekey=PHPStorm

; Log is not really needed. The documentation says:
; "Criticals, errors, and warnings always show up in the diagnostics log that you can view by calling xdebug_info()."

xdebug.log_level=7
xdebug.log=/app/xdebug.log
xdebug.discover_client_host=1

I am doing the same in Yii3, xdebug is loaded, I can see correct idekey when i call method xdebug_info(), but breakpoints do not work. I tried many changes, but nothing helped.

I setup my PhpStorm in the same way as in Yii2:

  • idekey is set
  • Docker server was added for localhost:80 and path mapping binds my project-root to /app

File /app/xdebug.log says only this. No connections:

[281473663876064] Log opened at 2026-04-24 09:53:12.013552
[281473663876064] [Config] WARN: Not setting up control socket with default value due to unavailable 'tsc' clock
[281473663876064] Log closed at 2026-04-24 09:53:29.962907

I added following records to .dockerignore

!/docker/**/php.ini
!/docker/**/xdebug.ini

Any ideas, please?

2

This configuration works with Ubuntu.

Configure Xdebug

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host = host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

The Yii 3 built-in dev server is running on port 8080.
PhpStorm Settings->PHP->Servers
Host: 0.0.0.0
Port: 8080
Path mapping:
path-to-src → /app/src

3
  1. Set correct host explicitly (disable auto-discovery)

xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal

  1. Make sure PhpStorm is listening
  • Click “Start Listening for PHP Debug Connections” (:electric_plug: icon)
  1. Check port (important)
  • Xdebug 3 default = 9003
  • PhpStorm must also use 9003
  1. Force debug trigger
    Sometimes Yii3 doesn’t auto-trigger:

xdebug.start_with_request=yes

OR test with:

?XDEBUG_SESSION=PHPSTORM

  1. Verify container can reach host
    Inside container:

ping host.docker.internal