Setting up PhpStorm with Xdebug for local development on Docker

gistfile1.txt

Install Xdebug

Install the extension via pecl (only for the local target):

# infrastructure/fpm/local/Dockerfile

&& apk add --no-cache --update tzdata linux-headers libxml2-dev postgresql-dev libpq \

# Install Xdebug via pecl (only for the local target)
&& pecl install -f xdebug && docker-php-ext-enable xdebug \

We want to enable xdebug only when we need it (due to the decrease in performance when the extension is enabled), hence we remove the default config file and enable/disable the extension in the application .ini file

# infrastructure/fpm/local/docker-php-ext-xdebug.ini
xdebug
; Note:
; comment; to disable debugging
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
xdebug.client_ip = "9003"
xdebug.log=/tmp/xdebug_remote.log

Install SSH

We will execute commands from PhpStorm via SSH in the application container.

we map port 2222 from the host system to port 22 of the application container and make sure that the codebase is shared as a volume between host and container.


Updates to .env

# make PhpStorm recognize incoming debug connections
# see https://www.jetbrains.com/help/phpstorm/debugging-a-php-cli-script.html
PHP_IDE_CONFIG=serverName=vmp-api

# application
APP_GROUP_NAME=application

# application
APP_SSH_PASSWORD=123456
APP_CODE_PATH_CONTAINER=/var/www/html
ENV=local
APP_USER_NAME=application
APP_USER_ID=10000
APP_GROUP_ID=10001

Build and start the containers.

docker-compose -f docker-compose.local.yml build
docker-compose -f docker-compose.local.yml up -d


Setup PhpStorm

We will configure a remote PHP interpreter that uses an SSH connection to run commands in the application container. 

At File | Settings | Tools | SSH Configurations create a new SSH Configuration named "Docker" with the following settings

Host: 127.0.0.1

Port: see APPLICATION_SSH_HOST_PORT in /docker-compose.local.yml

Username: see APP_USER_NAME in /. env

Authentication type: Password

Password: see APP_SSH_PASSWORD in /. env



PHP Interpreter

At File | Settings | PHP add a new PHP CLI interpreter that uses the new SSH Configuration

In addition, we define the path to the xdebug extension because it is disabled by default, but PhpStorm can enable it automatically if required.

/usr/local/lib/php/extensions/no-debug-non-zts-20200930/xdebug.so

add a custom PHP option for xdebug.client_host=host.docker.internal. That's the same value we use in infrastructure/fpm/local/docker-php-ext-xdebug.ini.

-dxdebug.client_host=host.docker.internal -dxdbug.client_port=9003

In the interpreter overview we must now configure the path mappings so that PhpStorm knows "which local file belongs to which remote one".

PHPUnit

phpunit is configured via File | Settings | PHP | Test Frameworks. First, we select the interpreter that we just added.

Then, we add the paths to the composer autoload script and the phpunit.xml configuration file.

PhpStorm will now execute tests using the PHP interpreter in the application container.


Debug code executed via php-fpm, cli or from a worker.

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 File | Settings | PHP | Debug. In Xdebug < 3 the default port was 9000 and in 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 serverName key in the environment variable PHP_IDE_CONFIG that we configured previously as serverName=vmp-api.

Setting a breakpoint in public/index.php and opening API in a browser will halt the execution as expected.