Configuring Remote PHP Interpreters

On this page:

• Prerequisite
• Important notes
• Configuring a remote PHP interpreter on a host accessible through SSH connection
  • Before you start
  • Configuring a PHP interpreter using SSH credentials
• Configuring a remote PHP interpreter in a Vagrant environment instance
  • Before you start
  • Configuring a PHP interpreter in a Vagrant instance
• Configuring a remote PHP interpreter on a remote host accessible through SFTP
  • Before you start
  • Configuring a remote PHP interpreter based on an SFTP server access configuration
• Configuring custom mappings

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 it is not, enable the plugin 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 set up in a Vagrant instance. The term remote PHP interpreter is used opposite to 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 bundled with PhpStorm and activated by default. If the plugin is not activated, enable it on the Plugins page of the Settings / Preferences Dialog as described in Enabling and Disabling Plugins.

Configuring 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 OS X, and click PHP under Languages&Frameworks.
2. On the PHP page that opens, click the button next to the Interpreter drop-down list in the Development environment section.
3. In the Interpreters dialog box that opens, click the Add toolbar button   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 and type the password.
   • To access the host through a pair of SSH keys, choose Key pair, then specify the path to the file where your private key is stored or the passphrase if you have configured it during the generation of the key pair.

   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 note 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 development environment configured on the selected remote host. By default PhpStorm suggests the /usr/bin/php folder. To specify another folder, click the Browse button 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 is 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 the Browse button next to the Configuration options field, and then create a list of entries in the Configuration Directives dialog box, that opens.

     • To add a new entry, click the Add button . 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 .
     • To change the order of entries, use the Up   and Down  buttons.

     Upon clicking OK, you return to the 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 bundled with PhpStorm and activated by default. If the plugin is not activated, enable it on the Plugins page of the Settings / Preferences Dialog 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.

Configuring 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 OS X, and click PHP under Languages&Frameworks.
2. On the PHP page that opens, click the button next to the Interpreter drop-down list in the Development environment section.
3. In the Interpreters dialog box that opens, click the Add toolbar button   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 development environment configured in the selected Vagrant instance. By default PhpStorm suggests the /usr/bin/php folder. To specify another folder, click the Browse button 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 is 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 the Browse button next to the Configuration options field, and then create a list of entries in the Configuration Directives dialog box, that opens.

     • To add a new entry, click the Add button . 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 .
     • To change the order of entries, use the Up   and Down  buttons.

     Upon clicking OK, you return to the 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 a 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 bundled with PhpStorm and activated by default. If the plugins are not activated, enable them on the Plugins page of the Settings / Preferences Dialog as described in Enabling and Disabling Plugins.
3. Make sure you have at least one PhpStorm-wide server access configuration of the type SFTP to establish access to the target host. To make a configuration available in all PhpStorm projects, clear the Visible only for this project check box in the Deployment: Connection Tab. See Creating a Remote Server Configuration for details.

Configuring 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 OS X, and click PHP under Languages&Frameworks.
2. On the PHP page that opens, click the button next to the Interpreter drop-down list in the Development environment section.
3. In the Interpreters dialog box that opens, click the Add toolbar button   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 type SFTP 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 Creating a Remote Server Configuration, section Mapping Local Folders to Folders on the Server and the URL Addresses to Access Them.

6. Specify the location of the PHP executable file in accordance with the development environment configured on the selected remote host. By default PhpStorm suggests the /usr/bin/php folder. To specify another folder, click the Browse button 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 is 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 the Browse button next to the Configuration options field, and then create a list of entries in the Configuration Directives dialog box, that opens.

     • To add a new entry, click the Add button . 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 .
     • To change the order of entries, use the Up   and Down  buttons.

     Upon clicking OK, you return to the 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 extension and configured options. Please note that the options specified in the Configuration Options field of the 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 OS X, 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 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 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 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 .