Damir's Corner.

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.

The 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 docker-compose.yml file:

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/app folder 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_autostart to make debugging available for all requests.
• In the image xdebug.remote_connect_back was enabled by default, but for some reason it did not work for me, so I disabled it.
• Instead, I set xdebug.remote_host to 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 docker-compose.yml:

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 Debug and set IDE key to docker (as configured in the image - the value was output by phpinfo()):

  

• To this configuration I added a Server named docker. I set Host and Port to localhost:8080 (as configured in Docker compose) and chose Xdebug as Debugger. I also added path mappings for my repository folder to the /app folder 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.