Docker Remote Interpreters

PhpStorm 2016.3 gives a much easier way to configure a Docker remote interpreter, with configuration done from an extra config option in the Interpreters pane of the IDE.

It’s previously been possible to work with a container based remote interpreter within PhpStorm, but the configuration was painful using the SSH settings, and it didn’t play well with all of the IDE’s features. In PhpStorm 2016.3, Docker interpreters become a first-class citizen.

Firstly, you’ll need to have a valid Docker configuration. If you are running your host on OSX and using Docker for Mac (as opposed to Docker Machine) then you’ll need to install an extra piece of software — you can find the instructions here. Once you have your Docker configuration setup, we can add the remote interpreter.

We can add a new interpreter from the preferences pane, by selecting Languages & Frameworks, then PHP, and clicking the […] button next to the interpreter drop down. Next, we click the [+] button to add a new interpreter and select Remote.


You can see that the new Docker option added. Once we’ve selected that, we need to pick the Docker configuration (it’s already configured it as mentioned above), and then the image name we wish to use for the container that has our PHP install, plus the path on the container to find the PHP executable.

Note: While just php will work fine in some cases, there have been reports that the full path to the PHP executable is needed. You can find this out by running the docker command docker-compose run php which php in the directory that your docker-compose.yml file is located where php is the container name. If you use another docker tool, substitute the docker-compose for that tool’s name.

Once we’ve clicked OK, you should see the new interpreter configured correctly and available to select. It’s worth giving it a more descriptive name (and I make it Visible for only this project as containers are usually project based).


Once PhpStorm has picked up your Docker settings, you’ll see the PHP version updating as PhpStorm runs some commands on the container to infer the configuration. Now that the remote interpreter is specified, we can also add the local path on the container to the Xdebug file so that we can step debug our command line scripts using the Xdebug On-Demand tool.

Now that we have the remote interpreter configured, we can use it as usual in any of the places we’d typically set an interpreter, including our test runner (PHPUnit, PhpSpec, Behat), code quality tools (PHPCS and PHPMD), and as previously mentioned, debugging. Let’s configure our PHPUnit test suite to run using this newly supplied Docker container.

We need to tell PhpStorm which interpreter and how to find PHPUnit for this project, we can do that in the PHPUnit settings pane, found under Languages & Frameworks, PHP, PHPUnit. You may already have a configuration here (if you’ve previously been running the unit tests locally, for example), but we need to create a new configuration by clicking the [+] and selecting By Remote Interpreter and then picking the interpreter we configured earlier.


Because PHPUnit is installed here using composer, I can just tell PhpStorm where to find the Composer autoloader as a local path on the container. Notice how we have a mapping from the project root to /opt/project.  Now we can click OK, and add a run configuration for PHPUnit by clicking the Edit Configurations option from the Run dropdown menu. We can add a new configuration using the [+] button, and selecting PHPUnit.


I like to use the configuration file to define test scope, so I’ve chosen Defined in the configuration file and used an alternate configuration file than the default, but you can do whatever you usually do here. Note that paths in this dialogue are relative to the host machine — not the container. Now, we can save the settings and run the test runner using the green play icon. Hopefully, everything is green.

Docker is an incredible innovation in using containers for development and deployment, and hopefully, these changes in PhpStorm open the door to being able to quickly develop and test your codebase against multiple versions of PHP easily. Try it yourself, and let us know what you think.

— Gary and the PhpStorm Team

About Gary Hockin

Gary Hockin has been creating code to power web applications for 15 years, the last three of them at an extraordinary level. He is handsome, talented, funny and articulate, and also extremely modest. Gary is a valued contributor to Zend Framework 2 and is a member of the community review team. He's married and has two wonderful children, and when he's not coding, writing about code, speaking about code or reading about code, he can usually be found in the pub playing pool.
This entry was posted in Cool Feature and tagged . Bookmark the permalink.
  • s.molinari

    Is there anything similar for Node in a Docker container?

    • Ekaterina

      WebStorm 2016.3 (now in Beta) can run and debug Node.js apps in a Docker container, here you can find more about that: But you can’t use remote Node.js for running linters, test runners and other node tools in WebStorm.

      • s.molinari

        Thank you for the info!

  • Nikolic Sladjan

    Hey @Gary, it works fine for phpunit, but when i try to setup code sniffer i have problem with volumes. I have code sniffer installed through composer and if I set this path “/my-project-path/vendor/bin/phpcs” as code sniffer path it fails.

    I realized that my project directory isn’t bound to docker container, even though i have configured everything on PHP interpreter settings page.

    Can you please confirm that it works for you… ? Maybe I missed something…

    P.S. When i run docker command “docker exec -it container-name /my-project-path/vendor/bin/phpcs –version” it works, so just to confirm that path is not an issue.

  • Raphaël Gonçalves

    Works fine for me too. But it seems Composer settings can’t use the docker interpreter yet?

  • Sergey Milegov

    I cannot alunch it on ubuntu.
    Always I have error Cannot find PHPUnit in include path (.:/usr/share/php:/usr/share/pear:).
    Phpstorm doesn’t provide “IDE_PHPUNIT_CUSTOM_LOADER” env (and other ide envs).
    Also phpunit tests always launch from “docker://my_container_name:latest/php /opt/.phpstorm_helpers/phpunit.php”
    But this folder (/opt/.phpstorm_helpers) is not existing. My volumes are:
    “/my_project_path/.phpstorm_helpers” this folder also is not existing.
    Even if I’ll add “IDE_PHPUNIT_CUSTOM_LOADER” env into phpunit config and add phpstorm helpers into /opt/.phpstorm_helpers I can launch just one file test. Tests with –filter and saved tests fails with the same error.
    What should I do?

  • Paweł Zaremba

    There seem to be too many escaping ” in a call to phpunit in docker.

    > docker://project/development:latest/php /opt/.phpstorm_helpers/phpunit.php –configuration /opt/project/app/phpunit.xml.dist –filter “/(Com\\TestsBundle\\Tests\\Command\\CommandTest::testExecute1|Com\\TestsBundle\\Tests\\Command\\CommandTest::testExecute2)$/”

  • DmitryVapelnik

    It does not works correctly and smoothly for osx with docker inside remote VmWare (or on another remote linux host like a docker-machine with generic driver)
    What is problem?
    We should mount directory with project on remote host into container on same directory in that placed project on osx local machine.
    For instance I have project MagicMaker
    It located on /Users/mage/Work/MagicMaker/project inside my osx host
    It located on /home/donkey/workspace/magicmaker inside my remote linux server
    So I should run docker container for tests with next mount volume configuration -v /home/donkey/workspace/magicmaker:/Users/mage/Work/MagicMaker/project
    With this configuration I can run single test (file, class, method) from IDE inside docker image but I still cannot debug this test: warning “Path mappings are not configured for selected interpreter. Please check hat mappings re properly configured at Docker Container settings or at Settings|PHP
    Have you any ideas for problem with debugging?