Here, I’m going to talk about configuring XDebug with PHPStorm and Docker.

1. Phpstorm Xdebug Docker
2. Xdebug Phpstorm Docker Ubuntu 18
3. Xdebug Php Docker

Pick the PHP Remote Debug template and click the +on the top left to add a new configuration (don't make the mistake of editing the template). Check 'Filter debug connection by IDE key' and set the IDE key to match the one in your XDebug config (for the above we'd use PHPSTORM). Add a server (the name doesn't matter). XDEBUGCONFIG - This variable allows to define some Xdebug configurations. The 'remote host' is the private ip of your host machine (the one your PHPStorm is running). The 'remoteport' is the port that PHPStorm will be listening for incoming Xdebug connections. These two settings allow PHPStorm and Xdebug to communicate. It wont work without this. The major difficulty in getting Xdebug (or Zend Debugger) working with PhpStorm and Docker integration is the correct configuration of the Docker container. In our case we're using a Dockerfile (we've already shown this config earlier and provided links to download it) to configure the container, including Xdebug-specific parameters, such as.

ℹ️ Important note: I will not talk about using it in an HTTP context. I have struggled so much in the past and never succeeded in configuring this, and I will probably never do it anyway.
I’m only using it when testing, with PHPUnit or Behat, and that’s perfect: it forces me to write more tests.

Having a working Docker environment

First of all, if we talk about Docker, you may refer to the series of blog posts I wrote about Docker, it might help you.

I will now consider you have a working PHP + Docker environment.

I also consider you already installed the Docker plugin for your PHPStorm IDE.

Make sure XDebug is available

Of course now you have a working Docker setup, but remember that XDebug must be present.

I usually install it in my Docker images by adding a RUN statement with (echo ' | pecl install xdebug).
This echo thing is a trick to force pecl to execute in a “non-interactive” mode, in order to let the Docker image be built automatically with no user interaction (which is not possible).

If you have PHP 7.2+, you can even make your debug-based test scripts cross-compatible with any platform thanks to extension loading by name.TL;DR: it means that you can do php -dzend_extension=xdebug instead of php -dzend_extension=xdebug.so for UNIX and php -dzend_extension=xdebug.dll for Windows. Yeah, it’s just about removing the extension.

To know whether XDebug is available, run php -dzend_extension=xdebug -i | grep xdebug.

If all XDebug options are displayed with their default/configured values, it works!

Start configuring!

Okay, let’s see ALL the steps that I go through to set this up.

First, the PHP interpreter

Let’s consider we have a php container running, configured in our docker-compose.yaml file.

PHPStorm will need a PHP interpreter.

For this, go to the File | Settings | Languages & Frameworks | PHP menu.

You should see something like this:

Now, you need to click on the [...] button at the right of the CLI Interpreter section in order to create/use a PHP interpreter.

You might have an existing PHP interpreter, but for the sake of the example, I’ll show you how to configure your PHP Docker container.

Add a new “Remote Interpreter” by clicking on the big + sign:

You should configure the remote interpreter to use Docker Compose and have something similar to this:

If it comes that you have the Server section to be empty, click on New and you may see something like this:

Note: I am using Windows, and I deliberately checked the Expose daemon on tcp://localhost:2375 without TLS checkbox in Docker For Windows configuration.I may update this post in the future for linux-specific config, so check out your docker machine in the first place to see if it can be linked to PHPStorm instead of using the legacy daemon tcp socket.

Here is my final configuration:

Some notes:

• You should decide on whether you want PHPStorm to use docker-compose run --rm php or docker-compose exec php.
  run guarantees an isolated container, but is slower because it needs to start the container first.
  exec is faster because it connects to a running container, but may have concurrence issues, even though it’s rare (feel free to share experience on that!).
• You can add Environment Variables for each interpreter. That’s nice if you want a “test-optimized” or a “profiling-optimized” one, etc.
• Note the Debugger extension field: if you write xdebug (or xdebug.so or xdebug.dll for PHP<=7.1), PHPStorm will automatically append -dzend_extension=xdebug when running a script in “Debug Mode”.

Phew! Now we have PHP, let’s install PHPUnit!

PHPUnit

You may have noticed that I’m a big Symfony fan, so we will take the example of a Symfony project here.

First, I do composer require phpunit. This will install the symfony/test-pack package, which is a package that requires a few other packages, with in particular the symfony/phpunit-bridge package.

The Symfony PHPUnit Bridge component comes with a modified version of PHPUnit (TL;DR: it’s a wrapper around PHPUnit) that will allow you to not require PHPUnit in your composer.json file. This might save some dependencies issues, because PHPUnit and your project might depend on same packages with different versions, and you don’t want that. Apart from that, the component provides some other nice features you may check on the docs.

Apart this “dependencies conflicts” theory, the PHPUnit team decided to use PHP-Scoper for their PHAR version, so if you use the phpunit.phar file, you will not have any conflict either, and that’s okay.

The good thing about this is that requiring it like this on a modern Symfony 4/5 project will install the PHPUnit Bridge Flex recipe that commes with a nice bin/phpunit script.
Very convenient for command-line, but don’t use it with PHPStorm (I will talk about this later).

Right after your composer require phpunit, execute bin/phpunit --version.

The wrapper provided by Symfony will install PHPUnit, find a good version for your system.

You can still override the version in the phpunit.xml.dist file created by the Flex recipe. I personally always update.

By default (as of the time I write this post), PHPUnit is installed via a big composer create-project command (you can find it here) into your bin/.phpunit/phpunit-{version}/ directory.

This point is important, because we will configure the PHPUnit “Run configuration” in PHPStorm by using this specific configuration.

Now! Comes the moment where we move back to PHPStorm!

First, click on the Add Configuration... button on the top-right section of your PHPStorm screen:

Then, add a PHPUnit configuration:

An empty PHPUnit configuration never works.

PHPStorm needs many things for it to work:

• A working PHP Interpreter
• A way to execute PHPUnit (autoloader, include path, executable…)
• An optional configuration file (but we must set it anyway, else PHPStorm’s PHPUnit process will not use the phpunit.xml.dist file at all)

So, to make it work, configure PHPUnit:

Add a new PHPUnit configuration with a Remote Interpreter:

Select the remote interpreter you created with your Docker configuration.

Then, we will tell PHPStorm to look for the PHPUnit executable.

When we ran bin/phpunit --version, the bridge installed PHPUnit in bin/.phpunit/phpunit-{version}, remember? We will pick the executable from there.Important: remember that the script path will be inside the Docker container, so be careful about paths.

Also remember to fill the Default configuration file field, else PHPUnit will not use any config.

Note: You might have slight differences in paths and versions depending on your Docker and PHPUnit configuration.

After that: PHPUnit is configured!

And for XDebug, we installed it.

Run a PHPUnit script in Debug mode with step-by-step debugging

To run in Debug mode, you have the little bug icon next to the “Run” button in your “Run configuration” top bar:

Click on it, and see if your project is tested!

Now, we’ll do step-by-step debugging, thanks to XDebug and PHPStorm’s integration.

Find some piece of code you want to test, and add a breakpoint. To do so, you can left-click in the left gutter of the line you want to stop by when running the test, or you can also place the cursor on the line and press Ctrl+F8 (Windows keymap).

Now, DEBUG!

The test will execute and PHPStorm will open a brand new tab so you can debug everything: stack trace, variables state, etc.

You can now start your step-by-step debugging, thanks to these buttons:

These buttons allow you to execute current line and go to next instruction, step into the function/method call, step out of the current function, etc.

Have fun doing better debugging than dump($var);exit;!

Late notes:

Why do I choose to not use bin/phpunit?

Well, because it simply does not run with PHPStorm.

The reason might be that as it is a wrapper around PHPUnit, Symfony adds features to it (or removes some), especially the one that installs PHPUnit in the first place.
Then, PHPStorm needs to execute this script before finishing the config, because it needs to know which version of PHPUnit is installed (either for auto-completion, autoload, or maybe PHPUnit-specific stuff I am not aware of).
The wrapper does not return the same contents than the native PHPUnit script, so PHPStorm will consider it either not working or incompatible.

This is why I use the native PHPUnit script that is installed by executing bin/phpunit --version

So, you’ve decided to try something new today and started a project from scratch. Your first step will be to set up a development environment: at the bare minimum, you’d want to run a web server and a PHP interpreter (preferably – with the debugging engine installed).

With Docker, you can start developing, running, and debugging your code in a matter of minutes!

Probably the easiest way to integrate Docker with PhpStorm is to use the PhpStorm Docker registry. It provides a selection of preconfigured Docker images curated by the PhpStorm team, which cover the most common PHP development needs.

Before you proceed, make sure that you have Docker installed on your machine: see how to do it on Windows and on macOS.

Defining the environment

To get started, we create a new project in PhpStorm. Next, we create a new file named docker-compose.yml , which will describe the configuration of the services comprising our app. In our case, it will be a single webserver service:
As you can see, we use the preconfigured Docker image comprising the Apache web server and PHP 7.1 with Xdebug.

Note that we use the host.docker.internal value to refer to the remote host. In Docker for Windows and Docker for Mac, it automatically resolves to the internal address of the host, letting you easily connect to it from the container.

An important note for Linux users: host.docker.internal on Linux is currently not supported. You’ll have to use your local machine’s hostname instead (to find out what your machine’s hostname is, simply execute hostname in Terminal).

The corresponding environment configuration section for Linux will read as follows:
See here for more details and possible workarounds.

Our environment is fully described:

We can now start using it by creating a dedicated run/debug configuration.

Phpstorm Xdebug Docker

Creating a run/debug configuration

Right-click docker-compose.yml and select Create… from the context menu:

In the dialog that opens, provide the name of the configuration and apply your changes:

Xdebug Phpstorm Docker Ubuntu 18

You can now start the configuration from the toolbar:

PhpStorm will automatically download the required image and start the web server:

That’s it: we’ve got everything ready for running and debugging our code!

Running and debugging code

Xdebug Php Docker

Let’s ensure that everything works as expected. To do this, we’ll create the most simple Hello world PHP file and try to debug it following the PhpStorm Zero-Configuration Debugging approach.

Since we already have Xdebug installed and configured, this will only require that you:

• Have a debugging extension installed and enabled for your browser:
• Set a breakpoint in your code:
  
• Enable listening to incoming debug connections in PhpStorm:

Now, simply open the page in the browser, and the debugging session will be started automatically:

We encourage you to further explore the PhpStorm Docker registry: while we’ve looked at a very simple case, you can use the described technique to provide your environment with, for example, a database, or an sftp server.
Using these Docker images will save you a lot of effort and let you start coding in a matter of a minute, or even less!

If you’d like to learn more about Docker and how to use it in PhpStorm, make sure to check out the excellent tutorial series by Pascal Landau, and PhpStorm documentation, of course.

Your JetBrains PhpStorm Team
The Drive to Develop