Loadingiron390

FeaturesNewsletter

PhpStorm has had Docker support for a while now, and using a Docker remote interpreter has been a relatively straightforward task for the last few releases. PhpStorm 2017.2 introduces native support for Docker Compose to make using Docker and PhpStorm even easier.

While Docker can handle single containers very nicely inside PhpStorm, often you should be defining multiple containers to handle different parts of your application; a container for your database, one for your web server, another for PHP, one for your memory cache, one for your queue and so on. This is considered the best practice when using Docker – one container per server, and in even rudimentary systems, these containers can ofter become numerous, with each container depending on one (or more) of the others.

This document contains information on how to download, install, and start using Symfony. For a more detailed explanation, see the Installation chapter of the Symfony Documentation. One of the options is to use a docker image from which PhpStorm will create a docker container that should contain a php interpreter. In this dialog, just select the server (this is the connection with the docker engine, the one we created in the first step), then select the docker image you want to use. Tutorial to set up PhpStorm for local PHP web development using Docker containers, Apache webserver, MySQL database, and PHPUnit testing framework for your P. I'm trying to run my PHPUnit tests from my Docker container within PHPStorm. Currently, I've provisioned both a Docker instance and CLI interpreter in PHPStorm, but PHPStorm is unable to open phpunit in my Docker container, complaining. It's the next video in a series about the usage of PHPUnit and various interpreters in PhpStorm. Here Gary Hockin, PhpStorm Developer Advocate, explains how.

Docker Compose is a tool for defining (and running) multiple container application in exactly the way defined above. You can define multiple containers in a `docker-compose.yml` file which (typically) lives in the root of your project, and then you can bring up your entire infrastructure using `docker-compose up`. This makes managing the web of containers needed to develop and (ultimately deliver your project using Docker Stack) much easier than having several individual docker files that need to be brought up in the right order.

If you’re not using Docker Compose and would like to learn more, I highly recommend this blog post by Matthew Setter.

PhpStorm 2017.2 makes it easier to use your PHP containers defined with Docker Compose as your remote interpreter of choice. When you’re adding your interpreter, still select From Docker, Vagrant, VM, Remote… and you’ll notice the new Docker Compose option.

The Server option allows you to pick which Docker server to connect to (Docker for Mac, Docker Machine or direct TCP connection). You then can tell PhpStorm which `docker-compose.yml` file to use as the Configuration file(s) and PhpStorm will then provide you with a list of containers to pick from in the Service drop-down. The Environment variables… setting allows you to set substitution variables for the `docker-compose.yml` file.

You can select any container that provides command-line PHP, and have multiple interpreters configured per-project – so if you want to have different containers for running PHP Unit configurations, one for running on PHP 5.6 and one for running on 7.1 for example, you can do that without a problem. You can still run your Behat, Codeception and PhpSpec tests using a Docker Compose interpreter, and you can find out more information about configuring those test frameworks in these videos.

Once you’ve configured your Docker Compose interpreter you’ll see that PhpStorm will infer the path mappings automatically from the `volumes` section of your configuration file.

Docker is an important area in both development and deployment so we’re always aiming to help make the integration with our IDEs as seamless as possible – we’re interested to hear what you have to say on the matter.

Note: Please note that Docker-compose configuration version 3 is not supported yet. We are working on it, please vote and follow the progress in the issue PY-22674.

– Gary & The PhpStorm Team

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

ℹ️ 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:

Phpstorm Docker Phpunit

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;!

Phpunit Phpstorm Docker Download

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