PhpStorm 2018.1 Help

Configuring Remote PHP Interpreters

In this section:

Prerequisite

Before you start working with remote interpreters, make sure that the SSH Remote Run plugin is enabled. The plugin is bundled with PhpStorm and is activated by default. If the plugin is not activated, enable it on the Plugins settings page of the Settings / Preferences Dialog as described in Enabling and Disabling Plugins.

Important notes

The term remote PHP interpreter denotes a PHP engine installed on a remote host or in a virtual environment. The term remote PHP interpreter is used as the opposite of local PHP interpreters that are installed on your computer, see Configuring Local PHP Interpreters.

You can access a remote PHP interpreter in the following ways:

  • Using SSH credentials to access the host where the PHP interpreter is installed.
  • Through access to the corresponding Vagrant instance.
  • According to a Server Access Configuration. This approach is also helpful if you are going to synchronize your project sources with the Web server on the target remote host.

Configuring a remote PHP interpreter on a host accessible through SSH connection

Before you start:

  1. Configure access to an ssh server on the target remote host and make sure this server is running.
  2. Make sure the PHP Remote Interpreter plugin is enabled. The plugin is activated by default. If the plugin is disabled, enable it on the Plugins settings page as described in Enabling and Disabling Plugins.

To configure a PHP interpreter using SSH credentials:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for macOS, and click PHP under Languages & Frameworks.
  2. On the PHP page that opens, click the browseButton button next to the CLI Interpreter drop-down list in the Development environment section.
  3. In the CLI Interpreters dialog box that opens, click Add new in the left-hand pane, then choose Remote on the context menu.
  4. In the Configure Remote PHP Interpreter dialog box that opens, choose the SSH Credentials method.
  5. Specify the name of the remote host and the port which the SSH server listens to. The default port number is 22.
  6. Specify your credentials to access the remote host in accordance with the credentials received during the registration on the server. Type your user name and choose the authentication method:
    • To access the host through a password, choose Password from the Auth type drop-down list, specify the password, and select the Save password checkbox to have PhpStorm remember it.
    • To use SSH authentication via a key pair, choose Key pair (OpenSSH or PuTTY). To apply this authentication method, you need to have your private key on the client machine and your public key on the remote server you connect to. PhpStorm supports private keys generated using the OpenSSH utility.

      Specify the path to the file where your private key is stored and type the passphrase (if any) in the corresponding text boxes. To have PhpStorm remember the passphrase, select the Save passphrase checkbox.

    • If your SSH keys are managed by a credentials helper application (for example, Pageant on Windows or ssh-agent on Mac and Linux), choose Authentication agent (ssh-agent or Pageant).

    To use an interpreter configuration, you need path mappings that set correspondence between the project folders, the folders on the server to copy project files to, and the URL addresses to access the copied data on the server. PhpStorm first attempts to retrieve path mappings itself by processing all the available application-level configurations. If PhpStorm finds the configurations with the same host as the one specified above, in the Host field, the mappings from these configurations are merged automatically. If no configurations with this host are found, PhpStorm displays an error message informing you that path mappings are not configured.

    To fix the problem, open the Deployment page under the Build, Execution, Deployment node, select the server access configuration in question, switch to the Mappings tab, and map local folders to folders on the server as described in Creating a Remote Server Configuration, section Mapping Local Folders to Folders on the Server and the URL Addresses to Access Them.

  7. Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. By default PhpStorm suggests the /usr/bin/php folder for remote hosts and Vagrant instances and php for Docker containers. To specify a different folder, click Browse browseButton and choose the relevant folder in the dialog box that opens. Note that the PHP home directory must be open for edit.
  8. When you click OK, PhpStorm checks whether the PHP executable is actually stored in the specified folder.
    • If no PHP executable is found, PhpStorm displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
    • If the PHP executable is found, you return to the Interpreters where the installation folder and the detected version of the PHP interpreter are displayed.
  9. Optionally, customize the configuration settings of the installation in the Additional area. In the Debugger extension text box, specify the path to Xdebug. This enables PhpStorm to activate Xdebug when it is necessary if you have disabled it in the php.ini file, see Configuring Xdebug for Using in the On-Demand Mode.
    • In the Configuration options field, compose a string of configuration directives to be passed through the -d command line option and thus add new entries to the php.ini file. The directives specified in this field override the default directives generated by PhpStorm, such as -dxdebug.remote_enable=1, -dxdebug.remote_host=127.0.0.1, -dxdebug.remote_port=9001, -dxdebug.remote_mode=req.

      For example, if you specify the -dxdebug.remote_mode=jit directive it will override the default -dxdebug.remote_mode=req directive and thus switch Xdebug to the Just-In-Time (JIT) mode, see Debugging in the Just-In-Time Mode for details.

      To do that, click Browse browseButton.png next to the Configuration options field, and then create a list of entries in the Configuration Options dialog box, that opens.

      • To add a new entry, click the Add button add.png. In the new line, that is added to the list, specify the name of the new entry and its value in the Name and Value text boxes respectively.

        You can add as many entries as you need, just keep in mind that they will be transformed into a command line with its length limited to 256 characters.

      • To delete an entry, select it in the list and click the Remove button delete.png.
      • To change the order of entries, use the Up arrowUp.png and Down arrowDown.png buttons.

      Upon clicking OK, you return to the CLI Interpreters dialog box, where the entries are transformed into a command line.

Configuring a remote PHP interpreter in a Vagrant environment instance

Before you start

  1. Make sure that Vagrant and Oracle's VirtualBox are downloaded, installed, and configured on your computer as described in Vagrant: Working with Reproducible Development Environments.
  2. Make sure the Vagrant plugin is enabled. The plugin is activated by default. If the plugin is disabled, enable it on the Plugins settings page as described in Enabling and Disabling Plugins.
  3. Make sure that the parent folders of the following executable files are added to the system PATH variable:
    • vagrant.bat or vagrant from your Vagrant installation. This should be done automatically by the Vagrant installer.
    • VBoxManage.exe or VBoxManage from your Oracle's VirtualBox installation.
  4. Configure the PHP development environment in the Vagrant instance to be used.

Learn more about using Vagrant with PhpStorm in Vagrant: Working with Reproducible Development Environments.

To configure a PHP interpreter in a Vagrant instance:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for macOS, and click PHP under Languages & Frameworks.
  2. On the PHP page that opens, click the browseButton button next to the CLI Interpreter drop-down list in the Development environment section.
  3. In the CLI Interpreters dialog box that opens, click Add new in the left-hand pane, then choose Remote on the context menu.
  4. In the Configure Remote PHP Interpreter dialog box that opens, choose the Vagrant method.
  5. Specify the Vagrant instance folder which points at the environment you are going to use. Technically, it is the folder where the VagrantFile configuration file for the desired environment is located. Based on this setting, PhpStorm detects the Vagrant host and shows it as a link in the Vagrant Host URL read-only field.

    To use an interpreter configuration, you need path mappings that set correspondence between the project folders, the folders on the server to copy project files to, and the URL addresses to access the copied data on the server. PhpStorm evaluates path mappings from the VagrantFile configuration file.

  6. Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. By default PhpStorm suggests the /usr/bin/php folder for remote hosts and Vagrant instances and php for Docker containers. To specify a different folder, click Browse browseButton and choose the relevant folder in the dialog box that opens. Note that the PHP home directory must be open for edit.
  7. When you click OK, PhpStorm checks whether the PHP executable is actually stored in the specified folder.
    • If no PHP executable is found, PhpStorm displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
    • If the PHP executable is found, you return to the Interpreters where the installation folder and the detected version of the PHP interpreter are displayed.
  8. Optionally, customize the configuration settings of the installation in the Additional area. In the Debugger extension text box, specify the path to Xdebug. This enables PhpStorm to activate Xdebug when it is necessary if you have disabled it in the php.ini file, see Configuring Xdebug for Using in the On-Demand Mode.
    • In the Configuration options field, compose a string of configuration directives to be passed through the -d command line option and thus add new entries to the php.ini file. The directives specified in this field override the default directives generated by PhpStorm, such as -dxdebug.remote_enable=1, -dxdebug.remote_host=127.0.0.1, -dxdebug.remote_port=9001, -dxdebug.remote_mode=req.

      For example, if you specify the -dxdebug.remote_mode=jit directive it will override the default -dxdebug.remote_mode=req directive and thus switch Xdebug to the Just-In-Time (JIT) mode, see Debugging in the Just-In-Time Mode for details.

      To do that, click Browse browseButton.png next to the Configuration options field, and then create a list of entries in the Configuration Options dialog box, that opens.

      • To add a new entry, click the Add button add.png. In the new line, that is added to the list, specify the name of the new entry and its value in the Name and Value text boxes respectively.

        You can add as many entries as you need, just keep in mind that they will be transformed into a command line with its length limited to 256 characters.

      • To delete an entry, select it in the list and click the Remove button delete.png.
      • To change the order of entries, use the Up arrowUp.png and Down arrowDown.png buttons.

      Upon clicking OK, you return to the CLI Interpreters dialog box, where the entries are transformed into a command line.

Configuring a remote PHP interpreter on a remote host accessible through SFTP

Before you start:

  1. Make sure that an ssh server is running on the target remote host and you have configured access to it.
  2. Make sure the PHP Remote Interpreter and Remote Hosts Access plugins are enabled. The plugins are activated by default. If the plugins are disabled, enable them on the Plugins settings page as described in Enabling and Disabling Plugins.
  3. Make sure you have at least one PhpStorm-wide server access configuration of the SFTP type to establish access to the target host. To make a configuration available in all PhpStorm projects, clear the Visible only for this project checkbox in the Deployment: Connection Tab. See Creating a Remote Server Configuration for details.

To configure a remote PHP interpreter based on an SFTP server access configuration:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for macOS, and click PHP under Languages & Frameworks.
  2. On the PHP page that opens, click the browseButton button next to the CLI Interpreter drop-down list in the Development environment section.
  3. In the CLI Interpreters dialog box that opens, click Add new in the left-hand pane, then choose Remote on the context menu.
  4. In the Configure Remote PHP Interpreter dialog box that opens, choose the Deployment Configuration method.
  5. From the Deployment Configuration drop-down list, choose the server access configuration of the SFTP type according to which you want PhpStorm to connect to the target host. If the settings specified in the chosen configuration ensure successful connection, PhpStorm displays the URL address of the target host as a link in the Deployment Host URL field.

    To use an interpreter configuration, you need path mappings that set correspondence between the project folders, the folders on the server to copy project files to, and the URL addresses to access the copied data on the server. By default, PhpStorm retrieves path mappings from the chosen server access (deployment) configuration. If the configuration does not contain path mappings, PhpStorm displays the corresponding error message.

    To fix the problem, open the Deployment page under the Build, Execution, Deployment node, select the relevant server access configuration, switch to the Mappings tab, and map the local folders to the folders on the server as described in Mapping local folders to folders on the server and the URL addresses to access them section.

  6. Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. By default PhpStorm suggests the /usr/bin/php folder for remote hosts and Vagrant instances and php for Docker containers. To specify a different folder, click Browse browseButton and choose the relevant folder in the dialog box that opens. Note that the PHP home directory must be open for edit.
  7. When you click OK, PhpStorm checks whether the PHP executable is actually stored in the specified folder.
    • If no PHP executable is found, PhpStorm displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
    • If the PHP executable is found, you return to the Interpreters where the installation folder and the detected version of the PHP interpreter are displayed.
  8. Optionally, customize the configuration settings of the installation in the Additional area. In the Debugger extension text box, specify the path to Xdebug. This enables PhpStorm to activate Xdebug when it is necessary if you have disabled it in the php.ini file, see Configuring Xdebug for Using in the On-Demand Mode.
    • In the Configuration options field, compose a string of configuration directives to be passed through the -d command line option and thus add new entries to the php.ini file. The directives specified in this field override the default directives generated by PhpStorm, such as -dxdebug.remote_enable=1, -dxdebug.remote_host=127.0.0.1, -dxdebug.remote_port=9001, -dxdebug.remote_mode=req.

      For example, if you specify the -dxdebug.remote_mode=jit directive it will override the default -dxdebug.remote_mode=req directive and thus switch Xdebug to the Just-In-Time (JIT) mode, see Debugging in the Just-In-Time Mode for details.

      To do that, click Browse browseButton.png next to the Configuration options field, and then create a list of entries in the Configuration Options dialog box, that opens.

      • To add a new entry, click the Add button add.png. In the new line, that is added to the list, specify the name of the new entry and its value in the Name and Value text boxes respectively.

        You can add as many entries as you need, just keep in mind that they will be transformed into a command line with its length limited to 256 characters.

      • To delete an entry, select it in the list and click the Remove button delete.png.
      • To change the order of entries, use the Up arrowUp.png and Down arrowDown.png buttons.

      Upon clicking OK, you return to the CLI Interpreters dialog box, where the entries are transformed into a command line.

  9. Click the Show phpinfo button to have PhpStorm display a separate information window where you can examine the installation details and view the list of loaded extensions and configured options. Please note that the options specified in the Configuration Options field of the CLI Interpreters dialog box are not listed.

Configuring a remote PHP interpreter in a Docker container

Before you start:

  1. Make sure that Docker is downloaded, installed, and configured on your computer as described in Docker.
  2. Make sure the Docker Integration, PHP Docker, and PHP Remote Interpreter plugins are installed and enabled. The plugins are activated by default. If the plugins are disabled, enable them on the Plugins settings page as described in Enabling and Disabling Plugins.
  3. Configure the PHP development environment in the Docker container to be used.

Learn more about using Docker with PhpStorm in Docker.

To configure a PHP interpreter in a Docker container:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for macOS, and click PHP under Languages & Frameworks.
  2. On the PHP page that opens, click the browseButton button next to the CLI Interpreter drop-down list in the Development environment section.
  3. In the CLI Interpreters dialog box that opens, click Add new in the left-hand pane, then choose Remote on the context menu.
  4. In the Configure Remote PHP Interpreter dialog box that opens, choose the Docker method.
  5. In the Server field, specify the Docker configuration to use, see Docker. Choose a configuration from the drop-down list or click the New... button next to it and create a new configuration in the Docker dialog box that opens.
  6. In the Image name field, specify the base Docker image to use. Choose one of the previously downloaded or your custom images from the drop-down list or type the image name manually, for example, php:latest or php:7.0-cli. When you later launch the run configuration, Docker will search for the specified image on your machine. If the search fails, the image will be downloaded from the image repository specified on the Registry page.
  7. Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. By default PhpStorm suggests the /usr/bin/php folder for remote hosts and Vagrant instances and php for Docker containers. To specify a different folder, click Browse browseButton and choose the relevant folder in the dialog box that opens. Note that the PHP home directory must be open for edit.
  8. When you click OK, PhpStorm checks whether the PHP executable is actually stored in the specified folder.
    • If no PHP executable is found, PhpStorm displays an error message asking you whether to continue searching or save the interpreter configuration anyway.
    • If the PHP executable is found, you return to the Interpreters where the installation folder and the detected version of the PHP interpreter are displayed.
  9. Optionally, customize the configuration settings of the installation in the Additional area. In the Debugger extension text box, specify the path to Xdebug. This enables PhpStorm to activate Xdebug when it is necessary if you have disabled it in the php.ini file, see Configuring Xdebug for Using in the On-Demand Mode.
    • In the Configuration options field, compose a string of configuration directives to be passed through the -d command line option and thus add new entries to the php.ini file. The directives specified in this field override the default directives generated by PhpStorm, such as -dxdebug.remote_enable=1, -dxdebug.remote_host=127.0.0.1, -dxdebug.remote_port=9001, -dxdebug.remote_mode=req.

      For example, if you specify the -dxdebug.remote_mode=jit directive it will override the default -dxdebug.remote_mode=req directive and thus switch Xdebug to the Just-In-Time (JIT) mode, see Debugging in the Just-In-Time Mode for details.

      To do that, click Browse browseButton.png next to the Configuration options field, and then create a list of entries in the Configuration Options dialog box, that opens.

      • To add a new entry, click the Add button add.png. In the new line, that is added to the list, specify the name of the new entry and its value in the Name and Value text boxes respectively.

        You can add as many entries as you need, just keep in mind that they will be transformed into a command line with its length limited to 256 characters.

      • To delete an entry, select it in the list and click the Remove button delete.png.
      • To change the order of entries, use the Up arrowUp.png and Down arrowDown.png buttons.

      Upon clicking OK, you return to the CLI Interpreters dialog box, where the entries are transformed into a command line.

  10. Click the Show phpinfo button to have PhpStorm display a separate information window where you can examine the installation details and view the list of loaded extensions and configured options. Please note that the options specified in the Configuration Options field of the CLI Interpreters dialog box are not listed.

Configuring custom mappings

If you use an interpreter accessible through SFTP connection or located on a Vagrant instance, the mappings are automatically retrieved from the corresponding deployment configuration or Vagrantfile. To specify additional mappings:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for macOS, and click PHP under Languages & Frameworks.
  2. From the Interpreter drop-down list, choose the remote interpreter for which you want to customize the mappings. The Path Mappings read-only field shows the path mappings retrieved from the corresponding deployment configuration or Vagrantfile, see the chapters above. To specify the custom mappings, click browseButton next to the Path Mappings field.
  3. The Edit Project Path Mappings Dialog that opens, shows the path mappings retrieved from the deployment configuration or Vagrantfile. These mappings are read-only.
    • To add a custom mapping, click new and specify the path in the project and the corresponding path on the remote runtime environment in the Local Path and Remote Path fields respectively. Type the paths manually or click browseButton and select the relevant files or folders in the dialog box that opens.
    • To remove a custom mapping, select it in the list and click delete.
Last modified: 27 July 2018

See Also