Docker config for PHP development
After a long break, I had to do some maintenance work on an old PHP project again and this time I did not like the idea of installing the tooling natively on my new development machine. I decided to rather configure a Docker image and run the project in it.
webdevops/php-nginx-dev image seemed like a good place to start. The
5.6 image tag is close enough to the PHP version running on the server. I started with the following
version: "3" services: php: image: webdevops/php-nginx-dev:5.6 working_dir: /app environment: - WEB_DOCUMENT_ROOT=/app ports: - "8080:80" volumes: - ./:/app:rw,cached
I did a minimum of customization:
- I mapped my entire project folder to the
/appfolder inside the image and set that folder
WEB_DOCUMENT_ROOT. (The image I chose comes with a fully documented set of environment variables that can be used for configuration.)
- I mapped port 80 from the image to port 8080 on my development machine.
This was sufficient to get the project running in Docker. However, I also wanted to be able to connect a debugger to the PHP runtime environment. Fortunately, the image has Xdebug pre-installed. According to the
phpinfo() output, it was still version 2. I had to change some settings to make it work:
- I enabled
xdebug.remote_autostartto make debugging available for all requests.
- In the image
xdebug.remote_connect_backwas enabled by default, but for some reason it did not work for me, so I disabled it.
- Instead, I set
host.docker.internal, which is the host IP if you are using Docker Desktop.
After mapping these settings to the image's environment variables, this was my final
version: "3" services: php: image: webdevops/php-nginx-dev:5.6 working_dir: /app environment: - WEB_DOCUMENT_ROOT=/app - XDEBUG_REMOTE_AUTOSTART=yes # debugging enabled for all requests - XDEBUG_REMOTE_CONNECT_BACK=no # disabled to use the IP below - XDEBUG_REMOTE_HOST=host.docker.internal # IP of docker host ports: - "8080:80" volumes: - ./:/app:rw,cached
The next step was configuring IntelliJ IDEA / PhpStorm:
I added a new PHP Remote Debug configuration, named it
Debugand set IDE key to
docker(as configured in the image - the value was output by
To this configuration I added a Server named
docker. I set Host and Port to
localhost:8080(as configured in Docker compose) and chose
Xdebugas Debugger. I also added path mappings for my repository folder to the
/appfolder on the server (also as configured in Docker compose):
That was all I needed for configuration. During development, I always have listening to incoming connections disabled. When I want to debug something, I set a breakpoint and start debugging with the
Debug configuration I configured. On the next request, execution stops at the breakpoint.
Docker Desktop is a great tool for configuring a development environment, regardless of what technology you use. In this post, I described how I created a Docker image for PHP development that gave me a great experience, including debugging, without having to install anything natively on my development machine.