Dockerfile

FROM production as dev

USER root

RUN apk add --no-cache $PHPIZE_DEPS \
    && pecl install xdebug-2.9.0 \
    && echo "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so" > /usr/local/etc/php/conf.d/20-xdebug.ini.disabled \
    && echo "xdebug.default_enable=1" >> /usr/local/etc/php/conf.d/20-xdebug.ini.disabled \
    && echo "xdebug.remote_enable=1" >> /usr/local/etc/php/conf.d/20-xdebug.ini.disabled \
    && echo "xdebug.remote_autostart=0" >> /usr/local/etc/php/conf.d/20-xdebug.ini.disabled \
    && echo "xdebug.remote_connect_back=1" >> /usr/local/etc/php/conf.d/20-xdebug.ini.disabled \
    && echo "xdebug.profiler_enable=0" >> /usr/local/etc/php/conf.d/20-xdebug.ini.disabled

docker-compose.override.yaml

version: xx

services:
    php-pfm:
        environment:
            XDEBUG_CONFIG: idekey=PHPSTORM remote_host=172.23.0.1 remote_port=10000

Remote host is host.docker.internal on mac and windows. On linux use docker inspect <container> | grep Gateway to find the host ip.

.PHONY: debug-start
debug-start: ## Enable xdebug
ifneq ($(CI), true)
	docker-compose exec -T -u root php-fpm sh -c "[ -e /usr/local/etc/php/conf.d/20-xdebug.ini ] && exit 0 \
		|| (mv /usr/local/etc/php/conf.d/20-xdebug.ini.disabled /usr/local/etc/php/conf.d/20-xdebug.ini && kill -USR2 1)"
endif

.PHONY: debug-stop
debug-stop: ## Disable xdebug
ifneq ($(CI), true)
	docker-compose exec -T -u root php-fpm sh -c "[ -e /usr/local/etc/php/conf.d/20-xdebug.ini.disabled ] && exit 0 \
		|| (mv /usr/local/etc/php/conf.d/20-xdebug.ini /usr/local/etc/php/conf.d/20-xdebug.ini.disabled && kill -USR2 1)"
endif