Overview

Hey folks, today I’m bringing you an update to a previous post where I talked about how to integrate xdebug with docker.

In this post, we’ll base our discussion around our erdiko-docker repository, that has a set of containers linked to give you a comfortable environment for web development. The structure is similar to the one in the original post, but using PHP 7 instead of PHP 5.6, and some useful tools like composer and phpunit included.

In the next section I’ll show you how to get things started.

Prepping environment

Let’s start cloning the docker repo:

git clone [email protected]:Erdiko/docker.git

Once it finishes, let change to the “php-fpm-xdebug-7_1″ branch that already has the xdebug installer.

At this point we are ready to run this container that has as example a simple Hello Word PHP script.

I’ll bet you don’t want to stop there! To make things more interesting we’re going to create a new Erdiko project. It could be placed wherever you want, if you don’t want to change the docker-compose file, you can create it inside the docker folder and name it “hello“, this way you will replace the built-in example.

Of course we won’t do that here, instead we will create a new project at same level of docker:

composer create erdiko/erdiko test_debugger

Now we need to map this project in the container. To do that just edit the docker-compose.yml in your docker project to looks like this:

version: '2.1'

services:

 data:
   image: busybox
   volumes:
     - ../test_debugger:/code

 webserver:
   extends:
     file: ./nginx/docker-compose.yml
   service: webserver
   volumes_from: [data]
   ports:
     - "8088:80"

 php:
   container_name: erdiko_php
   env_file: ./environment.env
   image: erdiko/php-fpm:latest-xdebug
   volumes_from: [data]

And this is it! Just start your container and you will have an Erdiko project up and running with a working debugger waiting for you.

Mac Tweaks

Our previous setup works perfectly in Linux/*nix based environments, but as a MacOS user I had some issues getting xdebug to connect.

After some research, I found that if you’re running Docker for Mac 17.05 or below, you still can continue base on previous post. In other hand, if you’re using Docker for Mac 17.06+ you will have to do some tweaks on xdebug.ini.

#!/bin/sh

# Install XDebug
cd /usr/local/bin
wget https://raw.githubusercontent.com/helderco/docker-php/master/template/bin/docker-php-pecl-install
chmod +x /usr/local/bin/docker-php-pecl-install
docker-php-pecl-install xdebug

echo "xdebug.remote_host=$(getent hosts docker.for.mac.localhost | awk '{ print $1 }')" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.remote_port=9001" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.remote_connect_back=0" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

echo "xdebug.idekey=PHPSTORM" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.default_enable=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.remote_enable=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.remote_autostart=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.remote_handler=dbgp" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
echo "xdebug.remote_autostart=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
## This is very helpful when something fails and you need a clue to start looking...
# echo "xdebug.remote_log=\"/tmp/xdebug.log\"" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

export XDEBUG_CONFIG="idekey=phpstorm"

Since inside the container the only way to communicate with xdebug is with static ip (ref. xdebug/remote#communication), you can see above that I set the xdebug.remote_host with IP took from docker.for.mac.localhost, a new Docker setting that provides the Docker machine IP (only for mac)

cat ~/Library/Containers/com.docker.docker/Data/database/com.docker.driver.amd64-linux/slirp/host

Other settings I had to tweak: xdebug.remote_port that I had to move to avoid collision with fpm, and xdebug.remote_connect_back is also now disabled to avoid override the remote host.

No worries, we already wrapped up those tweaks, you just need to change the tag in your docker compose to use “7.1-xdebug-mac”.

php: 
  container_name: erdiko_php 
  env_file: ./environment.env 
  image: erdiko/php-fpm:7.1-xdebug-mac 
  volumes_from: [data]

Setup the client

For practical purpose I will show you how to setup PHPStorm community IDE, but this is applicable for other clients.

They are two simple steps to add remote configurations, start going to “Run -> Edit Configurations” menu, click on green plus sign, and select “PHP Remote Debug”. In the new Remote, fill the Name field (I will use docker) and in the “Ide Key (session id)” put phpstorm.

In the Servers field, click on periods button (and this is the second step), it will open a new window and again click in the green plus sign. On the new Server, fill the Name field and for the other fields we will use docker values, it means Host-> erdiko.local and Port->8088.

It’s very important check “User Path Mappings” and bind local path with docker container ones.

Once you finish the configurations, click on the phone icon to start listening and then click on the green bug icon to start debugging.

It also works with other clients like MacGDBp, just keep in mind you need change the port and restart app.

Some screenshots as an example

In this screenshot you can see xdebug in action from Docker container. I just added a break in Example controller, in the bottom section you can see the trace of execution until it stops and variables current state.

Another interesting feature is the “inline variables values”. In the next picture you can see how step into shows $class contains an string with value “erdiko\core\helpers\FlashMessages”.

Final thoughts

I’m glad you are still here, hope you find this post useful, and please don’t hesitate coming up with any questions and feedback, it definitely will help us grow and bring you better things!

If you have found these docker examples helpful please take a look the github repo that powers the Docker Hub images, https://github.com/Erdiko/docker.  Github stars are always welcome too!