Xdebug with fpm-nginx

[emilebourquin]

To get Xdebug working with the fpm-nginx image, I did this:

If your docker-compose.yml file starts like this:

version: '3.8'

services:
   nginx_php:
      image: serversideup/php:8.2-fpm-nginx
...

replace that part with:

version: '3.8'

services:
   nginx_php:
      build:
         dockerfile: fpm-nginx_xdebug.dockerfile
         args:
            - PHP_VERSION=${PHP_VERSION}
      image: serversideup/php:${PHP_VERSION}-fpm-nginx_xdebug
...

In the same directory as docker-compose.yml , create a file named fpm-nginx_xdebug.dockerfile , and put this in it:

ARG PHP_VERSION

FROM serversideup/php:${PHP_VERSION}-fpm-nginx

RUN apt-get update \
    && apt-get install -y php-dev php-pear \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /usr/share/doc/* \
    && pecl install xdebug

ARG PHP_VERSION

# Set PHP_INI_DIR for docker-php-ext-enable to use
ENV PHP_INI_DIR=/etc/php/${PHP_VERSION}/fpm

ADD https://raw.githubusercontent.com/docker-library/php/master/docker-php-ext-enable /usr/bin/docker-php-ext-enable
RUN chmod u+x /usr/bin/docker-php-ext-enable

ARG PHP_VERSION

RUN docker-php-ext-enable xdebug \
    && echo "xdebug.mode=debug" >> /etc/php/${PHP_VERSION}/fpm/conf.d/docker-php-ext-xdebug.ini \
# -- EITHER --
    && echo "xdebug.start_with_request=yes" >> /etc/php/${PHP_VERSION}/fpm/conf.d/docker-php-ext-xdebug.ini \
# -- OR --
#    && echo "xdebug.start_with_request=trigger" >> /etc/php/${PHP_VERSION}/fpm/conf.d/docker-php-ext-xdebug.ini \
#    && echo "xdebug.trigger_value=PHPSTORM" >> /etc/php/${PHP_VERSION}/fpm/conf.d/docker-php-ext-xdebug.ini \
# Use a browser debugging extension from https://www.jetbrains.com/help/phpstorm/2023.1/browser-debugging-extensions.html
# -- END EITHER OR --
    && echo "xdebug.client_port=9003" >> /etc/php/${PHP_VERSION}/fpm/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host=host.docker.internal" >> /etc/php/${PHP_VERSION}/fpm/conf.d/docker-php-ext-xdebug.ini

RUN rm /usr/bin/docker-php-ext-enable \
    && apt-get purge -y php-dev php-pear

# Expose port 9003 for Xdebug
EXPOSE 9003

and start your Docker containers with this command:

PHP_VERSION=8.2 docker compose up nginx_php -d

Note: If the lines:

ADD https://raw.githubusercontent.com/docker-library/php/master/docker-php-ext-enable /usr/bin/docker-php-ext-enable
RUN chmod u+x /usr/bin/docker-php-ext-enable

freak you out, you could always manually copy the contents of https://raw.githubusercontent.com/docker-library/php/master/docker-php-ext-enable to a local file named docker-php-ext-enable , have a look at it, and instead of the ADD command, use:

COPY docker-php-ext-enable /usr/bin/docker-php-ext-enable

[jaydrogers]

Thanks for sharing your guide & helping the community 🙌

[IgordeOliveira]

this should be working in v3 images ?

[jaydrogers]

I don't see why it wouldn't work in the V3 images.

Looking at this again, it might be cool to set up the images to support this with a simple variable like ENABLE_XDEBUG=true.

If someone is interested in that, open up a feature request and I will definitely take a look: #66

[emilebourquin]

Now that install-php-extensions is included in the v3 image, I use this much simpler fpm-nginx_xdebug.dockerfile :

ARG PHP_VERSION

FROM serversideup/php:${PHP_VERSION}-fpm-nginx

USER root

RUN install-php-extensions gd xdebug

RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
 && echo "xdebug.start_with_request=trigger" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
 && echo "xdebug.trigger_value=PHPSTORM" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
 && echo "xdebug.client_port=9003" >> /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

# Expose port 9003 for Xdebug
EXPOSE 9003

USER www-data

[jaydrogers]

I really like where this is going, so I created a Feature request here: #408

I might swing around to this after a few other things 👍

[priyashpatil]

This feels wrong. If docker php is only meant for production.

[jaydrogers]

Didn't see this email until now 😃

Xdebug would not be installed by default --it's bascially for documentation only.

We would use Multistage builds to ensure single source of truth