Alexis PREVOT Technical project manager

To follow this tutorial, you must have the Xdebug extension installed on your container. In my example, I will use a Docker image of TheCodingMachine created by David Négrier. If you are starting a project, I recommend you to download one of our images here TheCodingMachine Docker PHP images

My base docker-compose.yml file looks like this:

app:
  image: thecodingmachine/php:7.2-v1-apache
  volumes:
    - .:/var/www/html
  environment:
    PHP_EXTENSION_XDEBUG: 1

Note: the PHP_EXTENSION_XDEBUG environment variable is specific to the thecodingmachine/php. It automatically configures Xdebug for the container.

Ports configuration

Keep in mind that PHPStorm opens port 9000 (by default) so Xdebug can connect to it. Our PHP container has Xdebug installed and Xdebug will try to connect to PHPStorm on port 9000 by default.

Xdebug phpstorm architecture

Out of the box, everything should be fine...

... except if port 9000 is already taken by another program on your host (your machine running PHPStorm).

Switching port

Port 9000 can be already used. In particular, if you are using PHP-FPM, the default port for PHP-FPM is 9000. This directly conflicts with the XDebug port.

If you want to use another port for Xdebug, follow the instructions below.

I recommend to use port 10000 instead.

Xdebug conf

Otherwise, just keep the default configuration port.

Registering your container server in PHPStorm

First, click on edit configurations, on the top right of PHPStorm window.

Edit Configurations

Then, follow the explanation in picture. All numbers are explained below.

Xdebug adding PHP web page

(1) Click on add button

(2) Confirm it by clicking on PHP Web Page

Xdebug add server

(3) Define a name for your project

(4) Click on ... to add a debug server

Xdebug add server configuration for Docker

(5) Once it's done, you are on debug server page. Click on "+" button to create a new one.

(6) Define a server name like docker_[your_project_name]

Path mappings in Xdebug server

(7) Add your host on port 80 using Xdebug

(8) Don't forget to click on Use path mappings

(9) We need to add path mapping. Indeed, from the point of view of Xdebug, the PHP application runs in the "/var/www/html" (we are in a container!). But for PHPStorm, my project is in my host machine directory! So we need to map the root of your PHP application to the "/var/www/html" directory, as shown on the image above.

At this point, you should be able to put a breakpoint in your code, start a debugging session and get the application to stop on the breakpoint. Jump to chapter "Run Xdebug" to see how to use Xdebug.

Xdebug CLI

All applications are not web-based. You might also want to debug a command-line application, from within your container. Let's see how to enable Xdebug for scripts (CLI)

In the docker-compose.yml, just add those environment variables

Docker-compose.yml

Remember that we are using our technical director's (David Négrier) images. That's why we can set PHP extensions, PHP .ini configurations into the docker-compose.yml. For more details, please look at this TheCodingMachine Docker PHP images.

(1) Enable the Xdebug extension

(2) If you are using a different Xdebug port, set your custom Xdebug port

(3) Add your Xdebug server name

(4) If you are using the default Xdebug port, please remove remote_port=[your_xdebug_port]. Otherwise, add your custom Xdebug port

Run Xdebug

Web

Place a breakpoint in your code and launch a debug session

Debug process for phpstorm

A new windows should open and you should access to PHPStorm debug bar.

Debug bar phpstorm

Scripts (CLI)

Click on Start Listening for PHP Debug connections

The button should appear like this :

Debug scripts cli docker - xdebug

Place a breakpoint in your code.

Now, just go into your php-apache container using docker exec -ti [container_id] bash and run your script manually.

Addentum: Installing Docker integration in PHPStorm

There is a very useful PHPStorm extension to quickly and efficiently manage your docker containers.

For example:

  • see the logs by container
  • have access to bash in a clique
  • quickly see environment variables
  • clear or restart containers

Before starting

  • You should check that the "Docker integration" is enabled on your IDE
  • Start the Docker daemon on you machine
  • Move to your favorite Docker project in PHPStorm

Configuring Docker

Now everything should be good, just go to Preferences... > Languages and Frameworks > PHP

Debug process for phpstorm

(1) Click on ... for openning the remote PHP interpreter

Debug docker cli interpreter

(2) Add a new CLI interpreter by clicking on From Docker, Vagrant, VM, Remote...

Debug cli docker server

(3) Click on Docker (remember that you should start Docker daemon)

(4) Add a new server

Debug docker server for phpstorm

(5) Select a server name

(6) Choose how to connect on Docker

(7) Make sure the connection is successful

Debug docker server for phpstorm

(8) Select your favorite default image

path server for phpstorm

(9) You need to set the path mapping for your code. By default, it's /opt/project in the container, just change it to /var/www/html

Debug docker button for phpstorm

Done! Just click on the Docker button on the bottom of PHPStorm window.

About the author

Alexis is an experienced technical project manager who manages several projects including Eco-Emballages (CITEO). Graduate of EPITECH, Alexis is specialized in PHP frameworks (Symfony, Laravel, Mouf) and he masters Docker.