Created
March 14, 2024 14:22
-
-
Save maclonghorn/2a6d2e44c2f421107a640e10fcf7ca61 to your computer and use it in GitHub Desktop.
Setting up PhpStorm with Xdebug for local development on Docker
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment