I'm mainly writing this down for my own benefit, but if some other poor lost soul out there can use this knowledge, then by all means please do so! I cannot support anything you do here directly, and as always, anything you break is your fault.

That all out of the way...

Dockerfile

Here are only the bits of dockerfile that I feel are relevant to this discussion:

FROM php:7.2-fpm

RUN pecl install xdebug
RUN docker-php-ext-enable xdebug

RUN touch /usr/local/etc/php/php.ini
ARG XDEBUG_INI=/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

RUN echo "xdebug.default_enable = off" >> ${XDEBUG_INI} \
&& echo "xdebug.remote_enable = on" >> ${XDEBUG_INI} \
&& echo "xdebug.remote_autostart = off" >> ${XDEBUG_INI} \
&& echo "xdebug.remote_connect_back = off" >> ${XDEBUG_INI} \
&& echo "xdebug.remote_port = 9001" >> ${XDEBUG_INI} \
&& echo "xdebug.idekey = DEBUGTHIS" >> ${XDEBUG_INI} \
&& echo "xdebug.remote_host = 172.21.0.1" >> ${XDEBUG_INI}

Replace 172.21.0.1 with the docker network connection to your local machine, try ifconfig and look for docker0.

PhpStorm

File -> Settings

Languages and Frameworks

Servers:
Create a new server
Set the host to be: 127.0.0.1 with port 80.
Check use path mapping, and create the proper mapping to your source directory.
Save

Run

Edit Configurations

Add a PHP Remote Debug configuration.
Filter the debug connection.

  • Use the server you previously created.
  • Set the IDE Key to "DEBUGTHIS"
    Hit apply, and this should validate.

Now go to your code

Set a breakpoint!
Download the browser extension if you haven't already.
Change the browser extension options to send "DEBUGTHIS" as the "session key".
Run the named debug configuration.
Load the code you're looking at, and the debugger should stop at your breakpoint.

Eureka!