Xdebug x Docker

README.md

Xdebug with Docker

With docker dev image

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-fpm:
        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

Without docker dev image

docker-compose.override.yaml

version: xx

services:
    php-fpm:
        volumes:
            - ./path/to/xdebug.ini:/usr/local/etc/php/conf.d/20-xdebug.ini.disabled
        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 \
		|| (cp /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 ] \
		&& rm /usr/local/etc/php/conf.d/20-xdebug.ini && kill -USR2 1"
endif

Try it out:

$ > docker-compose exec php-fpm php -v
PHP 7.4.6 (cli) (built: May 15 2020 01:43:37) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
$ > make debug-start
docker-compose exec -T -u root php-fpm sh -c "[ -e /usr/local/etc/php/conf.d/20-xdebug.ini ] && exit 0 \
	|| (cp /usr/local/etc/php/conf.d/20-xdebug.ini.disabled /usr/local/etc/php/conf.d/20-xdebug.ini && kill -USR2 1)"
$ > docker-compose exec php-fpm php -v
PHP 7.4.6 (cli) (built: May 15 2020 01:43:37) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Xdebug v2.9.6, Copyright (c) 2002-2020, by Derick Rethans
$ > make debug-stop
docker-compose exec -T -u root php-fpm sh -c "[ -e /usr/local/etc/php/conf.d/20-xdebug.ini ] \
	&& rm /usr/local/etc/php/conf.d/20-xdebug.ini && kill -USR2 1"
$ > docker-compose exec php-fpm php -v
PHP 7.4.6 (cli) (built: May 15 2020 01:43:37) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
$ > make debug-start
docker-compose exec -T -u root php-fpm sh -c "[ -e /usr/local/etc/php/conf.d/20-xdebug.ini ] && exit 0 \
	|| (cp /usr/local/etc/php/conf.d/20-xdebug.ini.disabled /usr/local/etc/php/conf.d/20-xdebug.ini && kill -USR2 1)"
$ > docker-compose exec php-fpm php -v
PHP 7.4.6 (cli) (built: May 15 2020 01:43:37) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Xdebug v2.9.6, Copyright (c) 2002-2020, by Derick Rethans

What's php-pfm? Past frocess manager?

@greg0ire nice catch ahah

I updated the gist with a version without a dev image

The other day I learned you could use cp /usr/local/etc/php/conf.d/20-xdebug.ini{.disabled,} and vice versa for this

The other day I learned you could use cp /usr/local/etc/php/conf.d/20-xdebug.ini{.disabled,} and vice versa for this

It doesn't seems to work 🤔 maybe because it's alpine and cp is from busybox ?

It has more to do with sh than with cp, this is shell expansion, and it's probably disabled.

Oh yeah, makes sense 👍