A guide to debugging everything in PhpStorm (IDE, Browser [fpm], cli and workers) In this tutorial, we will . We will also ensure that we can run . There is also a Youtube video to guide you through the full process set up our local dockerized PHP development environment to be used by PhpStorm and Xdebug PHPUnit tests from the command line as well as from PhpStorm https://www.youtube.com/watch?v=bZ1MiynqT98 All code samples are publicly available in my . You find the branch for this tutorial at . This tutorial was previously published on my personal blog at . Docker PHP Tutorial repository on github part-4-2-phpstorm-docker-xdebug-3-php-8-1-in-2022 PhpStorm, Docker and Xdebug 3 on PHP 8.1 in 2022 Introduction This article is an update of but will also cover the "remaining cases" of and . Setting up PhpStorm with Xdebug for local development on Docker debugging php-fpm php worker processes We will still rely on an that we connect to via an SSH Configuration instead of using the as I feel it's closer to what we do in CI / production. However, we will any longer but simply authenticate via password. always-running docker setup built-in docker-compose capabilities not use SSH keys This reduces complexity and removes any pesky warnings regarding "SSH keys being exposed in a repository". Install Tools Install composer is installed by pulling and simply "copying" the composer executable over to the base php image. In addition, composer needs the extensions and Composer the official composer docker image mbstring phar # File: .docker/images/php/base/Dockerfile

ARG ALPINE_VERSION
ARG COMPOSER_VERSION
FROM composer:${COMPOSER_VERSION} as composer
FROM alpine:${ALPINE_VERSION} as base

# ...

RUN apk add --update --no-cache  \
        php-mbstring~=${TARGET_PHP_VERSION} \
        php-phar~=${TARGET_PHP_VERSION} \

# ...

COPY --from=composer /usr/bin/composer /usr/local/bin/composer Because we want our build to be deterministic, we "pin" the composer version by adding a variable to the file COMPOSER_VERSION .docker/.env COMPOSER_VERSION=2.2.5 and using it in : .docker/docker-compose/docker-compose-php-base.yml services:
  php-base:
    build:
      args:
        - COMPOSER_VERSION=${COMPOSER_VERSION?} Install Xdebug Install the extension via (only for the target): apk local # File: .docker/images/php/base/Dockerfile

FROM base as local

RUN apk add --no-cache --update \
        php-xdebug~=${TARGET_PHP_VERSION} \
    # ensure that xdebug is not enabled by default
    && rm -f /etc/php8/conf.d/00_xdebug.ini We also don't want to enable immediately but only when we need it (due to the decrease in performance when the extension is enabled), hence we remove the default config file and disable the extension in the application file xdebug .ini # File: .docker/images/php/base/conf.d/zz-app-local.ini

; Note:
; Remove the comment ; to enable debugging
;zend_extension=xdebug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
xdebug.mode=debug See for an explanation of the setting (previously called in xdebug < 3). This will still work out of the box for Docker Desktop, but for Linux users we need to add the magic reference (we can't add it to the php base image because this is a runtime setting): Fix Xdebug on PhpStorm when run from a Docker container xdebug.client_host=host.docker.internal xdebug.remote_host host-gateway to all PHP containers services:
  service:
    extra_hosts:
      - host.docker.internal:host-gateway Finally, we need to add . The variable is defined as , where "dofroscra" is the name of the server that we will configure later for debugging. Because we need the same value in multiple places, the variable is configured in : the environment variable PHP_IDE_CONFIG to all PHP containers PHP_IDE_CONFIG=serverName=dofroscra .docker/.env PHP_IDE_CONFIG=serverName=dofroscra And then added in .docker/docker-compose/docker-compose.local.yml services:
  php-fpm:
    environment:
      - PHP_IDE_CONFIG=${PHP_IDE_CONFIG?}

  php-worker:
    environment:
      - PHP_IDE_CONFIG=${PHP_IDE_CONFIG?}

  application:
    environment:
      - PHP_IDE_CONFIG=${PHP_IDE_CONFIG?} Install PHPUnit PHPUnit will be installed via but will not be "baked into the image" for local development. Thus, we must run . To make this more convenient a make target for running arbitrary composer commands is added in : composer composer require in the container .make/01-00-application-setup.mk .PHONY: composer
composer: ## Run composer commands. Specify the command e.g. via ARGS="install"
    $(EXECUTE_IN_APPLICATION_CONTAINER) composer $(ARGS); This allows me to run from the host system to execute in the container. In consequence, will use the PHP version and extensions of the container to install the dependencies, yet I will still see the installed files locally because the codebase is configured as a volume for the container. make composer ARGS="install" composer install composer application Before installing phpunit, we must add the required extensions and to the container dom xml # File: .docker/images/php/base/Dockerfile

# ...

RUN apk add --update --no-cache  \
        php-dom~=${TARGET_PHP_VERSION} \
        php-xml~=${TARGET_PHP_VERSION} \ as well as rebuild and restart the docker setup via make docker-build
make docker-down
make docker-up Now we can add phpunit via make composer ARGS='require "phpunit/phpunit"' which will create a file and setup up the directory: composer.json vendor/ $ make composer ARGS='require "phpunit/phpunit"'
Using version ^9.5 for phpunit/phpunit
./composer.json has been created
Running composer update phpunit/phpunit
Loading composer repositories with package information
Updating dependencies
... I have also added a minimal config file phpunit.xml a test case at tests/SomeTest.php and a new Makefile for "anything related to qa" at : .make/01-02-application-qa.mk ##@ [Application: QA]

.PHONY: test
test: ## Run the test suite
  $(EXECUTE_IN_WORKER_CONTAINER) vendor/bin/phpunit -c phpunit.xml So I can run tests simply via make test $ make test
ENV=local TAG=latest DOCKER_REGISTRY=docker.io DOCKER_NAMESPACE=dofroscra APP_USER_NAME=application APP_GROUP_NAME=application docker-compose -p dofroscra_local --env-file ./.docker/.env -f ./.docker/docker-compose/docker-compose.yml -f ./.docker/docker-compose/docker-compose.local.yml exec -T --user application php-worker vendor/bin/phpunit
PHPUnit 9.5.13 by Sebastian Bergmann and contributors.

.                                                                   1 / 1 (100%)

Time: 00:00.324, Memory: 4.00 MB

OK (1 test, 1 assertion) Install SSH We will execute commands from PhpStorm via ssh in the container. As mentioned, we won't use a key file for authentication but will instead simply use a password that is configured via the variable in and passed to the image in . In addition, we map port from the host system to port of the application container and make sure that the codebase is shared as a volume between host and container application APP_SSH_PASSWORD .docker/.env .docker/docker-compose/docker-compose.local.yml 2222 22 application:
    build:
      args:
        - APP_SSH_PASSWORD=${APP_SSH_PASSWORD?}
    volumes:
      - ${APP_CODE_PATH_HOST?}:${APP_CODE_PATH_CONTAINER?}
    ports:
      - "${APPLICATION_SSH_HOST_PORT:-2222}:22" The container already contains and sets the password openssh ARG BASE_IMAGE
FROM ${BASE_IMAGE} as base

FROM base as local

RUN apk add --no-cache --update \
        openssh

ARG APP_SSH_PASSWORD
RUN echo "$APP_USER_NAME:$APP_SSH_PASSWORD" | chpasswd 2>&1

# Required to start sshd, otherwise the container will error out on startup with the message
# "sshd: no hostkeys available -- exiting."
# @see https://stackoverflow.com/a/65348102/413531 
RUN ssh-keygen -A

# we use SSH deployment configuration in PhpStorm for local development
EXPOSE 22

CMD ["/usr/sbin/sshd", "-D"] Setup PhpStorm We will configure a remote PHP interpreter that uses an SSH connection to run commands in the container. Before, , which was kinda confusing ("What is SFTP doing here?"), so we will use an instead and configure the path mappings in the interface application we have been using an SFTP Deployment configuration SSH Configuration Cli Interpreter SSH Configuration At create a new SSH Configuration named "Docker PHP Tutorial" with the following settings File | Settings | Tools | SSH Configurations Host: 127.0.0.1 Port: see in APPLICATION_SSH_HOST_PORT .docker/docker-compose/docker-compose.local.yml User name: see in APP_USER_NAME .make/.env Authentication type: Password Password: see in APP_SSH_PASSWORD .docker/.env PHP Interpreter At add a new PHP CLI interpreter that uses the new SSH Configuration File | Settings | PHP In addition, we define the because it is disabled by default but PhpStorm can enable it automatically if required. You can find the path in the container via path to the xdebug extension application root:/var/www/app# php -i | grep extension_dir
extension_dir => /usr/lib/php8/modules => /usr/lib/php8/modules
root:/var/www/app# ll /usr/lib/php8/modules | grep xdebug
-rwxr-xr-x    1 root     root        303936 Jan  9 00:21 xdebug.so We still need to by adding a custom PHP option for . That's the same value we use in . Fix Xdebug on PhpStorm when run from a Docker container xdebug.client_host=host.docker.internal .docker/images/php/base/conf.d/zz-app-local.ini In the interpreter overview we must now configure the so that PhpStorm knows "which local file belongs to which remote one". The remote folder is defined in via path mappings .docker/.env APP_CODE_PATH_CONTAINER=/var/www/app Afterward we can set a breakpoint e.g. in and start debugging: setup.php The screenshot shows that PhpStorm adds the Xdebug extension that we defined previously. PHPUnit is configured via . First, we select the interpreter that we just added phpunit File | Settings | PHP | Test Frameworks Then, we add the paths to the composer autoload script and the configuration file. phpunit.xml PhpStorm will now execute tests using the PHP interpreter in the container application Debugging First of all, if you haven't already please also take a look at the . Derick is doing a great job at explaining xdebug in detail including some helpful videos like official xdebug documentation Xdebug 3: Xdebug with Docker and PhpStorm in 5 minutes Debug code executed via PhpStorm This should already work out of the box. Simply set a break point, right-click on a file and choose "Debug '...'" Debug code executed via php-fpm, cli or from a worker For code that is executed "directly" by a container without PhpStorm, we first need to enable in the container by removing the in front of the extension in xdebug ; /etc/php8/conf.d/zz-app-local.ini ; Note:
; Remove the comment ; to enable debugging
zend_extension=xdebug To make this a little more convenient, we use dedicated make recipes for those actions in .make/01-01-application-commands.mk .PHONY: execute-in-container
execute-in-container: ## Execute a command in a container. E.g. via "make execute-in-container DOCKER_SERVICE_NAME=php-fpm COMMAND="echo 'hello'"
    @$(if $(DOCKER_SERVICE_NAME),,$(error DOCKER_SERVICE_NAME is undefined))
    @$(if $(COMMAND),,$(error COMMAND is undefined))
    $(EXECUTE_IN_CONTAINER) $(COMMAND);

.PHONY: enable-xdebug
enable-xdebug: ## Enable xdebug in the given container specified by "DOCKER_SERVICE_NAME". E.g. "make enable-xdebug DOCKER_SERVICE_NAME=php-fpm"
    "$(MAKE)" execute-in-container APP_USER_NAME="root" DOCKER_SERVICE_NAME=$(DOCKER_SERVICE_NAME) COMMAND="sed -i 's/.*zend_extension=xdebug/zend_extension=xdebug/' '/etc/php8/conf.d/zz-app-local.ini'"

.PHONY: disable-xdebug
disable-xdebug: ## Disable xdebug in the given container specified by "DOCKER_SERVICE_NAME". E.g. "make enable-xdebug DOCKER_SERVICE_NAME=php-fpm"
    "$(MAKE)" execute-in-container APP_USER_NAME="root" DOCKER_SERVICE_NAME=$(DOCKER_SERVICE_NAME) COMMAND="sed -i 's/.*zend_extension=xdebug/;zend_extension=xdebug/' '/etc/php8/conf.d/zz-app-local.ini'" To capture incoming requests, we need to make PhpStorm listen for PHP Debug connections via . Run | Start Listening for PHP Debug Connections The corresponding ports are configured at . In Xdebug < 3 the default port was and in File | Settings | PHP | Debug 9000 Xdebug 3 it is 9003 Finally, we need to add a server via File | Settings | PHP | Servers The name of the server must match the value of the key in the environment variable that we configured previously as . serverName PHP_IDE_CONFIG serverName=dofroscra php-fpm For we must process without restarting the container after we have activated via php-fpm restart the php-fpm xdebug kill -USR2 1 Since this is a pain to remember, we add a make target in .make/01-01-application-commands.mk # @see https://stackoverflow.com/a/43076457
.PHONY: restart-php-fpm
restart-php-fpm: ## Restart the php-fpm service
    "$(MAKE)" execute-in-container DOCKER_SERVICE_NAME=$(DOCKER_SERVICE_NAME_PHP_FPM) COMMAND="kill -USR2 1" So we can now simply run make enable-xdebug DOCKER_SERVICE_NAME=php-fpm
make restart-php-fpm Setting a breakpoint in and opening in a browser or via will halt the execution as expected. public/index.php http://127.0.0.1/ curl http://127.0.0.1/ cli Instead of triggering a PHP script via HTTP request, we can also run CLI scripts - think of the target for instance. To debug such invocations, we need to follow the same steps as before: make setup-db enable the extension in the container xdebug application "Listening for PHP Debug Connections" from PhpStorm Running the following make targets will trigger a breakpoint in : setup.php make enable-xdebug DOCKER_SERVICE_NAME=application
make setup-db php-workers And finally the same thing for long-running PHP processes (aka workers). Just as before: enable the extension in the container xdebug php-worker "Listening for PHP Debug Connections" from PhpStorm restart the php workers Running the following make targets will trigger a breakpoint in : worker.php make enable-xdebug DOCKER_SERVICE_NAME=php-worker
make restart-workers Wrapping up Congratulations, you made it! If some things are not completely clear by now, don't hesitate to leave a comment. Apart from that, you should now have a fully configured development setup that works with PhpStorm as your IDE. If you enjoy this kind of content, feel free to: follow me on Twitter check out my Blog and definitely take a look at the remaining parts of the Docker PHP Tutorial on Github Also Published Here

Too Long; Didn't Read

Making security fun one episode at a time

Using PhpStorm, Docker and Xdebug 3 on PHP 8.1

Too Long; Didn't Read

Pascal Landau

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Using PhpStorm, Docker and Xdebug 3 on PHP 8.1

Too Long; Didn't Read

Pascal Landau

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES