Created at 2020-10-10Updated at 2020-10-11Category Docker Tag Resource / Docker / PHP / PhpStorm / PhpUnit / Linux

• Phpstorm Docker Xdebug Not Working
• Phpstorm Xdebug Docker Cli
• Xdebug Php Docker

I have recently configured my windows 10 laptop with an additional SSD, so I could experiment with Linux. I have already installed Pop!_OS Git, PhpStorm and Docker. I haven’t installed PHP or Composer locally. Next I want to learn how to use this new environment. This is what I have found out so far.

Instruct XDebug to connect back to the IP where web request came from. Instruct XDebug to connect to host.docker.internal for command line execution or whenever “connect back” is not possible. Set PHPIDECONFIG env variable to serverName=localhost. This will tell your PhpStorm which server configuration to use. See next step for details. FROM php: 7.3 WORKDIR /var/www # Install dependencies RUN apt-get update # Install extensions RUN docker-php-ext-install mbstring bcmath # XDEBUG RUN pecl install xdebug RUN docker-php-ext-enable xdebug # This needs in order to run xdebug from PhpStorm ENV PHPIDECONFIG 'serverName=DockerApp' ADD php.ini /usr/local/etc/php.

Laravel Homestead is great, it supports multiple php versions, xDebug, MySQL and allows the user to install any other required software straight into the virtual machine.

Start with a Project

One of my favorite projects is the Gilded Rose Kata. I can clone that from github as follows:

Create docker-compose.yml

It is possible to run PHP cli without a docker-compose file, I have found it is easier to set up PhpStorm using this intermediate step.

PhpStorm has several preconfigured Docker containers, source:

They can be used as follows:

Php 7.3 CLI and XDebug 2.7

docker-compose.yml

The above will work for Linux, for Windows and MacOS the XDEBUG_CONFIG: will need the changed as follows:

Windows and MacOS

Windows and MacOS replace with XDEBUG_CONFIG:host.docker.internal, which will automatically resolve to the internal address of the host Docker is running on.

MacOS with local Homebrew php-fpm

If you use a local Homebrew php-fpm installation, port 9000 (which is the default debugging port) may become occupied. PhpStorm will remain silent on starting listening for incoming connections. If this is the case, in the Settings | Languages & Frameworks | PHP | Debug, set the Debug port to 9001, and use the following configuration line instead.

Apache, PHP 7.3, XDebug 2.7 and MySQL

For information this is the LAMP version (based on the phpstorm-workshop).

docker-compose.yml

Install dependencies using composer

To keep things simple the composer Docker container can be used to install the dependencies.

This is the script recommended on the docker hub composer page to avoid filesystem permissions problems

By default, Composer runs as root inside the container. This can lead to permission issues on your host filesystem. You can work around this by running the container with a different user:

On windows change $PWD for the full path to the project (note: forward slash / as separator), remove the line end and run the command as one line:

Alternatively, more complex projects will need specific PHP extensions to be installed, which are not included in the Composer Docker container. The following method could be used to install Composer, inside the container and install the dependencies.

1. Access bash in the php-cli container: docker-compose run --rm php-cli /bin/bash
2. Install Composer, by following the download instructions for Linux
3. Still, inside the container, install dependencies: php composer.phar install
4. Exit the container exit

Note: In Linux, using the second method Composer will create the vendor folder as root!

The permissions can be changed using chown:

Further information

There is a detailed description about running Docker containers as current host user.

The official documentation on Docker run and docker-compose cli reference.

Configure PhpStorm

Now the project has been cloned from GitHub and the dependencies have been installed. PhpStorm can be setup to use Docker. Thanks to Gary Hockin’s excellent YouTube video Running PHPUnit Tests in PhpStorm with Docker, the setup process can be easily replicated.

There is a four stage process:

1. Configure PhpStorm to use Docker
2. Configure the remote interpreter
3. Configure PhpUnit
4. Create Test runner

1. Configure PhpStorm to use Docker

• Settings (Ctrl + Alt + S)
• Search for Docker
  • Under Build, Execution, Deployment
• Click + to add
• Select Unix socket
  • Confirm connection was successful

2. Configure the default CLI interpreter

• Settings (Ctrl + Alt + S)
• Search for CLI interpreter
  • Under Language & Frameworks > PHP
• Click the ellipse button next to CLI Interpreter
• Click +
• Select From Docker, Vagrant…
• Choose Docker Compose
• Choose the Service from the drop down list (e.g. php-cli)

• Select OK
• Change the name e.g. Docker PHP

• Apply and OK
• Check the mapping
  • e.g. for a web project <Project root>→/var/www/html
  • e.g. for an app project <Project root>→/app

3. Configure PhpUnit

• Settings (Ctrl + Alt + S)
• Search for Test Frameworks
  • Under Language & Frameworks > PHP
• Click +
• Select PhpUnit from remote interpreter
• Choose the interpreter created above, e.g. Docker PHP
  • Confirm the path mappings, as above <Project root>→/app
  • Input the script path based on the mapping inside the container e.g. /app/vendor/autoload.php
  • Under Test runner, tick Default configuration script, type in the path, in the docker container. e.g. /app/phpunit.xml

4. Create the test runner

• Click Edit Configuration (next to run test button)
• Click + to add
• Select PHPUnit
• Under Test Runner choose Defined in the configuration file
• Name - e.g. Docker PHPUnit

• Click Play to run all the tests!

What about configuring xDebug?

Thanks to this setup, xDebug has been automatically configured! It will use the default PHP Interpreter, which was configured in step 2. A breakpoint can be set in the app or tests can be run with coverage :)

Enjoy the kata!

Edit: Added details on running commands on MacOS and Windows and small tweaks.

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:

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.

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.

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.

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

(1) Click on add button

(2) Confirm it by clicking on PHP Web Page

(3) Define a name for your project

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

(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]

(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

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

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

Scripts (CLI)

Click on Start Listening for PHP Debug connections

The button should appear like this :

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

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

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

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

(4) Add a new server

Phpstorm Docker Xdebug Not Working

(5) Select a server name

(6) Choose how to connect on Docker

(7) Make sure the connection is successful

(8) Select your favorite default image

(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

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.

Related articles

Latest articles

Phpstorm Xdebug Docker Cli

Open-source matters

At TheCodingMachine, we are using open-source tools daily to build our projects. And since we and our clients are ripping huge benefits from these open-source products, we also try to 'give back' to the open-source community.

Freelance Developer?

At TheCodingMachine, we are always looking for top freelance developers to work with us on our next state-of-the-art project.
Interested in developing quality projects? We love good work and we pay fairly.

We are hiring!

Living in France? We are actively looking for developers and project leaders in our Paris and Lyon office.

About us

At TheCodingMachine, we strive to develop websites , extranets, intranets and business web applications in PHP and JavaScript for a wide range of clients.
Do not hesitate to contact us!

Best practices

When writing code, we expect it to be of the best possible quality. To enforce this quality, we redacted our own 'best practices' described in a dedicated website.
We are happy to share those with you!

Packanalyst

Xdebug Php Docker

We are the happy parents of Packanalyst, a free online service that lets you search any possible PHP class or interface referenced on Packagist.
Pretty useful for open-source developer to keep an eye on who is using what class/interface of your packages.