Configure remote PHP interpreters

A remote PHP interpreter is a PHP engine that is installed on a remote host or in a virtual environment. The term remote PHP interpreter is opposite to a local PHP interpreter that is installed on your local computer.

In PhpStorm, you can configure access to a remote PHP interpreter via SSH, in a Docker container, via Docker Compose, Vagrant, or WSL:

By using the SSH configuration type, you can access a PHP interpreter installed to a server on a remote host.

Configure a PHP interpreter using SSH

Press Ctrl+Alt+S to open settings and then select PHP.
On the PHP page that opens, click next to the CLI Interpreter list.
In the CLI Interpreters dialog that opens, click in the left-hand pane, then choose From Docker, Vagrant, VM, WSL, Remote... from the popup menu.

In the Configure Remote PHP Interpreter dialog that opens, choose the SSH method and fill out the method parameters as follows:

Field	Description
SSH configuration	Choose one of the created SSH configurations from the list, or click and create a new configuration as described in Create SSH configurations.
PHP interpreter path	Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. For remote hosts, PhpStorm by default suggests the /usr/bin/php location. To specify a different folder, click and choose the relevant folder in the dialog that opens. Note that the PHP home directory must be open for editing.

Field

Description

SSH configuration

Choose one of the created SSH configurations from the list, or click and create a new configuration as described in Create SSH configurations.

PHP interpreter path

Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment.

For remote hosts, PhpStorm by default suggests the /usr/bin/php location.

To specify a different folder, click and choose the relevant folder in the dialog that opens. Note that the PHP home directory must be open for editing.

Click OK. PhpStorm checks whether a PHP executable is actually stored in the folder specified in the PHP interpreter path field.
- 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 CLI Interpreters dialog where the installation folder and the detected version of the PHP interpreter are displayed.
Clicking next to the PHP executable field opens a separate information window with the installation details and the list of loaded extensions and configured options.
Click Apply and OK to save the changes and return to the PHP settings page.
Besides the configured remote PHP interpreter in the CLI Interpreter field, the PHP settings page will now display a read-only Path mappings field.
Path mappings are used to 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 in the selected SSH configuration, 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.
Click in the Path mappings field and map local folders to the folders on the server manually. For details, see Configure custom mappings.

By using the Docker configuration type, you can access a PHP interpreter installed in a Docker container.

Configure a PHP interpreter in a Docker container

Press Ctrl+Alt+S to open settings and then select PHP.
On the PHP page that opens, click next to the CLI Interpreter list.
In the CLI Interpreters dialog that opens, click in the left-hand pane, then choose From Docker, Vagrant, VM, WSL, Remote... from the popup menu.

In the Configure Remote PHP Interpreter dialog that opens, choose the Docker method and provide the connection parameters:

Field

Description

Server

Specify the Docker configuration to use. For more information, refer to Configure the Docker daemon connection settings. Select a configuration from the list or click New... and create a new configuration on the Docker page that opens.

Image name

Specify the base Docker image to use. Choose one of the previously downloaded or your custom images from the 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 Docker Official Images repository on the Docker Registry page.

PHP interpreter path

Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment.

For Docker containers, PhpStorm by default suggests the php location.

Click OK. PhpStorm checks whether a PHP executable is actually stored in the folder specified in the PHP interpreter path field.
- 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 CLI Interpreters dialog where the installation folder and the detected version of the PHP interpreter are displayed.
Clicking next to the PHP executable field opens a separate information window with the installation details and the list of loaded extensions and configured options.
Click Apply and OK to save the changes and return to the PHP settings page.
Besides the configured remote PHP interpreter in the CLI Interpreter field, the PHP settings page will now display read-only Path mappings and Docker container fields.
PhpStorm attempts to retrieve path mappings automatically by processing all the available application-level configurations. To set custom path mappings, click in the Path mappings field and map local folders to the folders on the server manually. For details, see Configure custom mappings.

By using the Docker Compose configuration, you can access a PHP interpreter running in a multi-container Docker Compose environment.

Configure a PHP interpreter using Docker Compose

Press Ctrl+Alt+S to open settings and then select PHP.
On the PHP page that opens, click next to the CLI Interpreter list.
In the CLI Interpreters dialog that opens, click in the left-hand pane, then choose From Docker, Vagrant, VM, WSL, Remote... from the popup menu.

In the Configure Remote PHP Interpreter dialog that opens, choose the Docker Compose method and provide the connection parameters:

Remote interpreter via Docker Compose dialog

Field	Description
Server	Specify the Docker configuration to use. For more information, refer to Configure the Docker daemon connection settings. Select a configuration from the list or click New... and create a new configuration on the Docker page that opens.
Configuration file(s)	Specify the docker-compose configuration files to use. The base configuration file located in the project root is selected by default. To select a different file or several files, click and select the desired configuration file in the Docker Compose Configuration Files dialog that opens.
Service	Choose the service corresponding to the container the PHP development environment is set up in.
Environment Variables	Optionally, provide the environment variables. For more information, refer to Docker Compose run configuration settings.
PHP interpreter path	specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. For Docker containers, PhpStorm by default suggests the php location.

Click OK. PhpStorm checks whether a PHP executable is actually stored in the folder specified in the PHP interpreter path field.
- 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 CLI Interpreters dialog where the installation folder and the detected version of the PHP interpreter are displayed.
Clicking next to the PHP executable field opens a separate information window with the installation details and the list of loaded extensions and configured options.
In the Lifecycle area of the CLI Interpreters dialog, choose how the Docker container for the selected service should be managed by PhpStorm.
- Always start a new container ('docker-compose run'): choose this option to have the container started via the run command. The container will be restarted upon each run.
- Connect to existing container ('docker-compose exec'): choose this option to have the container started once, and then connect to it via the exec command.
Click Apply and OK to save the changes and return to the PHP settings page.
Besides the configured remote PHP interpreter in the CLI Interpreter field, the PHP settings page will now display a read-only Path mappings field.
PhpStorm attempts to retrieve path mappings automatically by processing all the available application-level configurations. To set custom path mappings, click in the Path mappings field and map local folders to the folders on the server manually. For details, see Configure custom mappings.

By using the Vagrant configuration, you can access a PHP interpreter installed on the corresponding Vagrant instance.

Configure a PHP interpreter in a Vagrant instance

Press Ctrl+Alt+S to open settings and then select PHP.
On the PHP page that opens, click next to the CLI Interpreter list.
In the CLI Interpreters dialog that opens, click in the left-hand pane, then choose From Docker, Vagrant, VM, WSL, Remote... from the popup menu.

In the Configure Remote PHP Interpreter dialog that opens, choose the Vagrant method and provide the connection parameters:

Field	Description
Vagrant instance folder	Specify the 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.
PHP interpreter path	Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. For Vagrant instances, PhpStorm by default suggests the /usr/bin/php location. To specify a different folder, click and choose the relevant folder in the dialog that opens. Note that the PHP home directory must be open for editing.

Field

Description

Vagrant instance folder

Specify the 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.

PHP interpreter path

Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment.

For Vagrant instances, PhpStorm by default suggests the /usr/bin/php location.

To specify a different folder, click and choose the relevant folder in the dialog that opens. Note that the PHP home directory must be open for editing.

Click OK. PhpStorm checks whether a PHP executable is actually stored in the folder specified in the PHP interpreter path field.
- 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 CLI Interpreters dialog where the installation folder and the detected version of the PHP interpreter are displayed.
Clicking next to the PHP executable field opens a separate information window with the installation details and the list of loaded extensions and configured options.

By using WSL, you can access a PHP interpreter installed in a Linux environment through the Windows Subsystem for Linux compatibility layer.

Configure a PHP interpreter using WSL

Press Ctrl+Alt+S to open settings and then select PHP.
On the PHP page that opens, click next to the CLI Interpreter list.
In the CLI Interpreters dialog that opens, click in the left-hand pane, then choose From Docker, Vagrant, VM, WSL, Remote... from the popup menu.

In the Configure Remote PHP Interpreter dialog that opens, choose the WSL method and provide the connection parameters:

Field	Description
Linux distribution	Choose one of the installed Linux distributions to use from the drop-down list.
PHP interpreter path	Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment. For WSL, PhpStorm by default suggests /usr/local/bin/php. To specify a different folder, click and choose the relevant folder in the dialog that opens. Note that the PHP home directory must be open for editing.

Field

Description

Linux distribution

Choose one of the installed Linux distributions to use from the drop-down list.

PHP interpreter path

Specify the location of the PHP executable file in accordance with the configuration of the selected remote development environment.

For WSL, PhpStorm by default suggests /usr/local/bin/php.

To specify a different folder, click and choose the relevant folder in the dialog that opens. Note that the PHP home directory must be open for editing.

Click OK. PhpStorm checks whether a PHP executable is actually stored in the folder specified in the PHP interpreter path field.
- 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 CLI Interpreters dialog where the installation folder and the detected version of the PHP interpreter are displayed.
Clicking next to the PHP executable field opens a separate information window with the installation details and the list of loaded extensions and configured options.

Provide additional configuration options

Press Ctrl+Alt+S to open settings and then select PHP.
On the PHP page that opens, click next to the CLI Interpreter list.

Customize the configuration settings of the PHP installation in the Additional area of the CLI Interpreters dialog.

Field	Description
Debugger extension	Specify the path to the Xdebug executable file for debugging in On-Demand Mode. This way, PhpStorm can activate Xdebug even if it has been disabled in the php.ini file.
Configuration options	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.mode=debug, -dxdebug.client_host=127.0.0.1, -dxdebug.client_port=9003, -dxdebug.start_upon_error=default For example, if you specify the `-dxdebug.start_upon_error=yes` directive, it will override the default `-dxdebug.start_upon_error=default` directive and thus switch Xdebug to the Just-In-Time (JIT) mode. For more information, refer to Debug in the Just-In-Time mode. -dxdebug.remote_enable=1, -dxdebug.remote_host=127.0.0.1, -dxdebug.remote_port=9000, -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. For more information, refer to Debug in the Just-In-Time mode. To do that, click next to the Configuration options field, and then create a list of entries in the Configuration Options dialog that opens. To add a new entry, click . 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 fields 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 . To change the order of entries, click or . Upon clicking OK, you return to the CLI Interpreters dialog, where the entries are transformed into a command line.

Field

Description

Debugger extension

Specify the path to the Xdebug executable file for debugging in On-Demand Mode. This way, PhpStorm can activate Xdebug even if it has been disabled in the php.ini file.

Configuration options

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.mode=debug,
    -dxdebug.client_host=127.0.0.1,
    -dxdebug.client_port=9003,
    -dxdebug.start_upon_error=default

For example, if you specify the -dxdebug.start_upon_error=yes directive, it will override the default -dxdebug.start_upon_error=default directive and thus switch Xdebug to the Just-In-Time (JIT) mode. For more information, refer to Debug in the Just-In-Time mode.

    -dxdebug.remote_enable=1,
    -dxdebug.remote_host=127.0.0.1,
    -dxdebug.remote_port=9000,
    -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. For more information, refer to Debug in the Just-In-Time mode.

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

To add a new entry, click . 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 fields 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 .
To change the order of entries, click or .

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

Configure custom mappings

If you use an interpreter accessible through SSH connection or located on a Vagrant instance or in a Docker container, the mappings are automatically retrieved from the corresponding deployment configuration, Vagrantfile, or Dockerfile.

Press Ctrl+Alt+S to open settings and then select PHP.
From the Interpreter 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, Vagrantfile, or Dockerfile. To specify the custom mappings, click next to the Path Mappings field.
The Edit Project Path Mappings dialog shows the path mappings retrieved from the deployment configuration, Vagrantfile, or Dockerfile. 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 that opens.
- To remove a custom mapping, select it in the list and click .

Switch between configured PHP interpreters on the fly

Press Ctrl+Shift+A and start typing Change PHP interpreter. In the suggestion list, select the Change PHP interpreter action.
If necessary, you can assign a keyboard shortcut for this action either directly in the suggestions list by pressing Alt+Enter, or at a later point as described in Keyboard shortcuts.
In the popup menu that opens, select one of the configured local or remote PHP interpreters.

The selected interpreter will be set as the default project interpreter on the PHP page of the Settings dialog (Ctrl+Alt+S) . This will also affect configurations that use the default project interpreter (test frameworks', quality tools', and run/debug configurations) and commands run in the PhpStorm terminal.

Last modified: 11 October 2024