PHP Remote Interpreters Support in PhpStorm 8 EAP

Posted on by Mikhail Vink

Support for php_remote_int_introPHP remote interpreters has been introduced in PhpStorm 8 EAP. It lets us use a PHP interpreter over SSH installed on any remote environment, to run/debug application and run testing tools remotely.

Using a remote interpreter instead of a local one gives us an opportunity to get advantages of a PHP interpreter installed in a production-like environment (be it a physical server, a virtualized environment such as Vagrant, or any other). That way we can make sure there will be no inconsistencies when the application is finally deployed to production.

In this blog post we will look into configuring and using PHP remote interpreters for PHPUnit.

PHP Remote Interpreters Configuration

A remote interpreter can be configured in the same way as a local one in Settings | PHP | Interpreter | …


All the current PHP interpreters will be listed. Click the + button to add a new one, then select Remote to add a new remote interpreter.


The PHP remote interpreter dialog displays:


A PHP remote interpreter can be configured:

  • Manually – all the SSH connection details should be provided in the dialog (Host, Port, User name, Auth type, Password, etc);
  • From the deployment server configuration – after selecting a deployment server, all the connection details will be filled in by PhpStorm from deployment server settings. Please note that SFTP deployment with valid mappings should be configured first in Settings | Deployment to have the button Fill from deployment server settings available.
  • From the Vagrant configuration – after selecting Vagrant Configuration Folder, all the connection details will be filled in by PhpStorm from the current Vagrant configuration.


After you click OK, the connection will be tested and (in case of success) the remote interpreter will be added to the list of PHP interpreters in PhpStorm.


Please note that a valid deployment server with correct mappings should be configured in any case so that PhpStorm knows what file should be executed on the remote environment.

PHPUnit via SSH

One of the most important use cases for PHP remote interpreters is running PHPUnit tests remotely, and now it’s already possible.

In order to configure a running PHPUnit remotely, just add a new PHPUnit Setting by Remote Interpreter in Settings | PHP | PHPUnit.


Select the appropriate remote interpreter in the dialog to proceed:


The PHPUnit configuration will be added, and the usual PHPUnit testing workflow will be valid (with PHPUnit configuration through run/debug configurations dialog).

Please note that PHPUnit configuration will be used according to the default PHP interpreter setting for the project. The same PHPUnit configuration can be used for working with local and remote interpreter, it will rely on the default PHP interpreter setting in the project.

Support for PHP remote interpreters is still a work in progress, so please have a look at known and planned issues and take a minute to report any bugs or feature requests to our issue tracker.

Develop with pleasure!
-JetBrains PhpStorm Team

Comments below can no longer be edited.

40 Responses to PHP Remote Interpreters Support in PhpStorm 8 EAP

  1. Marcel Hernandez says:

    April 9, 2014

    The use of a remote interpreter would make it possible to Xdebug from the IDE unit tests that were running in a Vagrant box, am I right?

    • Mikhail Vink says:

      April 9, 2014

      Well, that’s not only about debugging (remote debugging was possible without remote interpreters), but mostly for running PHPUnit tests on Vagrant, so I suppose the answer is yes, you are right.

      • jimmy says:

        July 10, 2014

        I can now run tests with remote php interpreter, but I can’t start the debug session. from the console, I can see the message:

        ssh://xxxx@ -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=17001 -dxdebug.remote_host=

        and with the same port and machine, I can use eclipse to debug my web app (not the phpunit tests, that’s why I choose phpstorm:)).

        anything I missed?

        • jimmy says:

          July 10, 2014

          and I have set the correct debug port(17001) in phpstorm->php->debug

          • jimmy says:

            July 10, 2014

            and can successfully set up debug session for the web app. but why the phpunit tests failed to debug?

          • Liubov Melnikova says:

            July 11, 2014

            Did you try Zero configuration approach: ?
            Breakpoints are just not hit or you are getting any errors?

          • jimmy says:

            July 12, 2014

            the breakpoints in the phpunit tests just not hit.

            for the zero configuration guide, like I said, I can successfully debug the app itself in phpstorm.

            is there something related to the php cli debug? as tests are executed from command line with remote php. I tried this one:
            with no luck:(

          • jimmy says:

            July 12, 2014

            seeing from the console, actually phpstorm is running this php file: /home/xxxx/.phpstorm_helpers/phpunit.php

            so actually I need debug this file instead of my tests file, but how?

          • jimmy says:

            July 12, 2014

            finally figured it out, I’m using symbol link inside the server, and in the ‘deployment option’, I set the mapping to the link folder, seems phpstorm can’t handle it. so I change all mappings (both in the deployment and the server config) to the absolute path. and it works!

  2. Michael Knoll says:

    April 19, 2014

    Is it somehow possible to either

    * use Mac OS’s keychain for the private key password
    * or use the authentication mechanism of the terminal (which for me is set up to log in into my Vagrant box automatically using my private key and passphrase)

    This would make remote interpreters even more convenient!

    Thanks for a response,


    • Liubov Melnikova says:

      April 24, 2014

      1. Do you mean password manager for Mac?
      2. If you want it to be used automatically from terminal, it’s not possible, unless you can setup private key and passphrase in Vagrant settings.

  3. Rüdiger Scheumann says:

    April 23, 2014

    Is it possible to give detailed informations on how to configure a valid deployment server with correct mappings (using a vagrant vm)? I now tried for hours to get php(unit) running remote and a complete example would be of great help.

    I assume the problem in my case is paths on my host machine not getting mapped to paths on my vagrant box. I get error messages stating “Cannot open file “/Volumes/…”, which is the absolute path on the host and therefore can’t be found in the vm’s filesystem.

    Vardumping $argv in .phpstorm_helpers/phpunit.php shows that $argv[2] (directory containing tests to be executed) is pointing to a directory on my host machine “/Volumes/…/Project” and not to “/home/vagrant/project” on my vagrant box. So I assume the phpunit helper script is okay, but something is wrong with the arguments PhpStorm passes to that helper script. If I ssh into the vagrant box and run phpunit manually, it runs fine.

    Thanks for help!

      • Stephen Lewis says:

        May 29, 2014

        I have exactly the same problem as Rüdiger (and have similarly spent hours trying to get this to work). Unfortunately, the article you linked to doesn’t address this problem at all.

        Please note that PHPUnit configuration will be used according to the default PHP interpreter setting for the project. The same PHPUnit configuration can be used for working with local and remote interpreter, it will rely on the default PHP interpreter setting in the project.

        This seems to suggest that you can set up a new “PHPUnit Run / Debug Configuration”, and it will automatically use the PHP interpreter on the Vagrant box, provided that is the project default.

        The only interpreter in my project is the one on the VM, but the PHPUnit Preferences pane still insists on displaying (and defaulting to) “Local”, and there’s no way of deleting it. I can only assume there’s something else wrong with my configuration, but goodness knows what.

        This post is great, right up until the point at which you gloss over the final few steps, saying “the usual PHPUnit testing workflow will be valid (with PHPUnit configuration through run/debug configurations dialog)”.

        Please provide the missing pieces, so we can get this working.

        Thank you,

      • Stephen Lewis says:

        May 29, 2014

        An update on this…

        I finally got it working through random trial and error. Turns out you must configure the “local” PHPUnit preferences correctly, even though PHPStorm isn’t using them. Quite why this is required is still a mystery to me.

        In my case, I’m using the Laravel framework, so for both the local server and the Vagrant “interpreter”, I needed to specify:

        1. “Use custom loader”: set to vendor/autoload.php (full path locally, and on the server).
        2. “Default configuration file”: set to phpunit.xml (full path locally, and on the server).

        Hopefully this will save somebody else a few hours of flailing about aimlessly.


        • Bob says:

          June 5, 2014

          Hmm, I still can’t seem to get this working.

          When I start a test, PHPStorm tries to run the test on the remote vagrant server, but uses the local path. So the error is:

          bash: line 0: cd: /Users/myname/Sites/ProjectName/public/protected: No such file or directory

          While it should offcourse use:

          Any ideas? Am I missing something?

          • Maxim Kolmakov says:

            June 9, 2014

            Bob, you need to configure the valid SFTP deployment server with correct mappings in Settings->Deployment. PhpStorm will use those mappings to translate your local path to remote one.

          • Ryan Castle says:

            August 15, 2014

            For vagrant, hacking on the SFTP deployment settings (instead of “In Place”) worked for me too eventually. Although the setup is different than how it would be for a regular deployment. I’ve spent a whole day on various options. I suppose the docs will improve with a full release.

            I think there are also some places where instead of choosing the built-in vagrant install you have to choose your SFTP server. For instance, in the “Remote Interpreter” setup choose “Deployment configuration” instead of “Vagrant” (and pick the SFTP deployment you created).

            Also PHPUnit paths to “phpunit.phar” and to “phpunit.xml” need to refer to the counterparts inside vagrant.

        • happy time says:

          June 23, 2014

          This worked!!! thx

    • Shannon Warren says:

      October 1, 2014

      The documentation could use lots of work. I am using Laravel Homestead Virtualbox. This should work with other boxes long as you are using composer install version of PHPUnit. If you are not using composer version of PHPUnit you will select the right option for you.

      Steps to get this working:
      If using Vagrant you still have to create a SFTP deployment server
      My deployment SFTP server paths
      Local path: /Users/Jdoe/Code/Laravel/public
      Deployment path on server: /home/vagrant/Code/Laravel/public
      Web path on server: /
      (public) is the doc root in the vagrant box so if i navigate to I would get the index.php in public.

      Under main PHP settings:
      Set PHP language level
      Select the new interpreter (add new if needed)
      This Interpreter can use any of the settings
      SSH Credentials, Vagrant, or Deployment configurations

      Under PHP->PHPUnit
      You must set Local and “By Remote Interpreter”
      For Local
      Set “Use custom autoloader”
      Default configuration file: /Users/Jdoe/Code/Laravel/vendor/autoload.php (host path to autoload.php)
      Default bootstrap file: /Users/Jdoe/Code/Laravel/bootstrap/autoload.php (host path to bootstrap autload.php)

      Create “By Remote Interpreter”
      Set “Use custom autoloader”
      Default configuration file: /home/vagrant/Code/Laravel/vendor/autoload.php (remote path to autoload.php)
      Default bootstrap file: /home/vagrant/Code/Laravel/bootstrap/autoload.php (remote path to bootstrap autoload.php)

      Run/debug config:
      Create new PHPUnit (not PHPUnit on server)
      Default config file:
      in “Test scope:” use “Defined in configuration file”

  4. Miikka Virtanen says:

    May 6, 2014

    Is it possible to use remote interpreters for running Composer? I’d like to run Composer on my local VM that has a shared folder to the project root.

  5. Steve W. says:

    June 9, 2014

    Is this feature limited to PHPStorm? I’m using IDEA 13.1.3 with the PHP plugin version 134.1456 and the “add” context menu in the Interpreters window only shows “Other Local…” as an option. Is there another plugin that I’m missing, or a confiugration setting that is preventing this from showing?

    • Maxim Kolmakov says:

      June 10, 2014

      This feature will be available via plugin in IDEA 14 EAP.

      • Régis B. says:

        November 3, 2014

        IDEA 14 RC3 is out and this is still not included. Will it be available on release ?

  6. Michael Hunger says:

    July 11, 2014

    If you cannot find the by remote interpreter option on a mac lion system. Try to scroll. The options bar only one option and does not show a scroll bar. Try to scroll anyway and the option appears magically 🙂

    • Maarten Balliauw says:

      July 14, 2014

      The latest EAP has a fresh UI which gives a better view on all options.

  7. Using Behat in PhpStorm | JetBrains PhpStorm Blog says:

    July 24, 2014

    […] Behat configuration can be always changed in Settings | PHP | Behat. You can also use Behat via Remote Interpreter. […]

  8. Martin says:

    August 28, 2014

    Is there any plan to add this feature to Webstorm? I am running node app inside of Vagrant and it would be nice to ssh into box..

  9. Ricardo says:

    September 1, 2014


    I’m trying to set this up with the latest version of PHPStorm 8 EAP but as soon as I end the connection configuration (both vagrant and manual methods) phpstorm gets stuck trying to connect and it never comes back, I have to then kill the java process. Is this feature broken?

  10. Tim Bezhashvyly says:

    September 12, 2014

    This tutorial missing the final section (scrieenshot). Once everything is configured how do you run the test remotely?

  11. PhpStorm 8 发布,PHP 集成开发环境 | 服务器维护 says:

    September 17, 2014

    […] PHP 5.6;支持 Blade template engine, WordPress, and Drupal 8;支持 Behat;支持 Remote PHP interpreters;调试和测试的改进;支持  AngularJS, spy-js (a JavaScript and […]

  12. Ionut Zailic says:

    September 22, 2014

    The “Remote Interpreters Support” it’s a great feature. Thank you for this. But there are still some problems; the most annoying one is that the IDE doesn’t know to lookup after the libraries from the remote host(VM). In this way you will gain a lot of fake “not-found” warnings – i.e. the case when PHPUnit resides on the remote host.

  13. Milica says:

    October 23, 2014

    Hi folks I want to use php interpreter on Vagrant machine. When I try Test connection I have this error : Connection to failed. When I ssh from cli to vagrant it works. Has someone idea what can be wrong?


Subscribe for updates