Docker: How to use PhpStorm to debug remote Docker container for Web Development using Xdebug

• docker
• phpstorm
• debug

There are many tools that can be used for debugging when developing a web app using PHP. These debugging tools are very useful in a local development environment, you can view the states of variables, indicate line breaks etc. However, these tools become difficult to use when you decide to include Docker in your workflow.

This post outlines the configuration needed to incorporate the debugging power of the PhpStorm IDE to your PHP based web app. We will not be using the official Docker Support in PhpStorm. This is because we are not integrating PhpStorm fully with Docker, we are merely using PhpStorm for debugging purposes.

This post assumes you have the following set up:

• Using Docker (with the official PHP image)
• Using PhpStorm (version 10.0.*)
• Using Docker in a VirtualBox setup either using docker-machine or an Ubuntu VM.

My Set Up

The following describes my set up of the development environment. You do not need to use the exact set up, but the configuration to follow assume that you are using this set up.

1. A local VirtualBox VM running Ubuntu 16.04 Xenial with the latest docker-engine installed. I did not opt to run Docker using Docker for Mac or Docker Toolbox, I just ssh into my Ubuntu VM and run docker natively from there.
2. My docker containers are based on the LAMP stack.
3. I have PhpStorm installed on my host (not my VM). The PhpStorm project is located in a local folder on my host. This local folder is then mounted as a shared folder on the VirtualBox VM. So changes I make to this folder is reflected in the VM and vice versa. In the VM, this shared folder is also mounted as a volume on the docker container. So: changes in code in PhpStorm is reflected in the VM and hence reflected in the docker container.

Configuration

With the above set up, we essentially want to use PhpStorm to debug a remote server.

The configuration used in this set up is essentially a summary from these two sources:

• Debug your PHP in Docker with Intellij/PHPStorm and Xdebug
• Debug your PHP in Docker with Intellij/PHPStorm and Xdebug (forked from the above)

1. Create your own Dockerfile with your own configuration and add the below to install Xdebug:

       FROM php:5
       ...
       RUN yes | pecl install xdebug \
           && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini \
           && echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/xdebug.ini \
           && echo "xdebug.remote_autostart=off" >> /usr/local/etc/php/conf.d/xdebug.ini
   

2. Build your image

3. Start a container with your image but with the following environment variables:

   • XDEBUG_CONFIG: "remote_host=10.0.2.2"
   • PHP_IDE_CONFIG: "serverName=my.local"
   • You can either the run the container with the -e option or in a docker-compose.yml file.

4. In PhpStorm go to Languages & Frameworks > PHP > Servers > and set the following:

   • Name should match PHP_IDE_CONFIG previously set
   • You can modify the Host and Port to your own settings (the hostname that you use to ssh to the VM)

5. All set!

Usage

1. Set a break point in your code base in PhpStorm.
2. Access the web page on your local machine.
3. On the web page navigate to the section where it will trigger the break point.
4. The web page will begin loading and PhpStorm will prompt for your attention.
5. On first run, PhpStorm will ask you to map the directories. Follow the prompts and you are done!