IntelliJ IDEA 2017.2 Help

Creating a PHP Debug Server Configuration

This feature is supported in the Ultimate edition only.

The following is only valid when PHP Plugin is installed and enabled!

The term PHP debug server configuration denotes the settings that ensure HTTP access for debugging engines to interact with local and remote Web servers and set correspondence between files on the server and their local copies in the IntelliJ IDEA project. The settings from debug server configurations are used when debugging with run/debug configurations of the type PHP Web Application or PHP Remote Debug and during Zero-Configuration Debugging sessions.

You can create a debug server configuration manually from scratch or import some settings from a server access (deployment) configuration (see Configuring Synchronization with a Web Server for details).

On this page:

Defining a debug server configuration manually

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or IntelliJ IDEA | Preferences for macOS. Expand the Languages & Frameworks node, and then click Servers under PHP.

    Alternatively, click browseButton.png next to the Server drop-down list in the Run/Debug Configuration: PHP Web Application dialog box.

    In either case, the Servers page opens with the left-hand pane showing all the available debug server configurations. Click add.png on the toolbar and specify the debug server settings in the right-hand pane.

  2. Specify the debug server configuration name.
  3. Specify the host where the application is run and the port to access it.
  4. From the Debugger drop-down list, choose the debugging engine to use.
  5. Specify how IntelliJ IDEA will set up correspondence between files on the server and their local copies. Based on these mappings, IntelliJ IDEA will open local copies of currently processed files.

    Path mappings in PHP Debug Server configurations look very similar to the path mappings in server access (deployment configurations. Unfortunately, they cannot be reused, as deployment configurations uses relative paths while PHP Debug Servers configurations rely on absolute paths.

    • Select the Use path mappings check box if you are working on a remote Web server, that is, when the Web server is on a physically remote host, or the Web server is installed on your machine but your project is outside the Web server document root. Also select the check box if you are using symlinks.

      Map the absolute paths to the files and folders on the server with absolute paths to your project files in the local file system using the Path on server and File/Directory fields respectively.

      • File / Directory: This read-only field displays the files and folders of the current project. Select a file or a folder to be used as the local copy.
      • Path on server: In this filed, specify the absolute path to the file or folder on the target server to which the selected local file or folder corresponds. Type the path manually or select it from the drop-down list.

    • Clear the Use path mappings check box if you are working right on your Web server so your project root is under the server document root. In this case the absolute paths to the files on the Web server and the absolute paths to the corresponding files in your project are the same.

    If you do not specify any path mappings and start debugging an application that is not under the server document root, IntelliJ IDEA displays an error message:

    ps_debug_mappings_not_configured_error_message.png
    The Click to set up path mappings link brings up the Resolve Path Mappings Problem dialog box, where you can define the path mappings:
    ps_debug_mappings_not_configured_fix.png

    When you click OK and leave the dialog box, IntelliJ IDEA selects the Use path mappings check box on the Servers page automatically.

  6. Select the Shared check box to share the debug server configuration across a team. The host/port settings and the path mappings are stored in the .idea/php.xml file is available to all team members through a version control system. Note that mappings are shared only for directories inside the project.

Importing settings from a server access (deployment) configuration

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or IntelliJ IDEA | Preferences for macOS. Expand the Languages & Frameworks node, and then click Servers under PHP.

    Alternatively, click browseButton.png next to the Server drop-down list in the Run/Debug Configuration: PHP Web Application dialog box.

    In either case, the Servers page opens with the left-hand pane showing all the available debug server configurations. Click icon injection move to project make global on the toolbar. The Import from Deployment Configuration Dialog dialog box opens.

  2. From the Deployment drop-down list, choose the server access configuration (deployment configuration) to copy the server access settings from. The list contains all the available deployment configurations. To create a new configuration, click browseButton.png and specify new settings in the Deployment: Connection Tab dialog box that opens.
  3. Depending on the type of the server access configuration chosen from the Deployment drop-down list, specify one of the following:
    • For an FTP, SFTP, or FTPS server access configuration, specify the absolute path to the server deployment root. This path will be added as a prefix to the path from the Root Path text box on the Deployment: Connection Tab.

      If you are not sure about this absolute path, you can open the Remote Host tool window, choose the required deployment configuration, position the cursor at the root folder, and choose Copy Path on the context menu, see Accessing Files on Web Servers for details. Alternatively, contact your hosting provider.

    • For Local or mounted folder, type the absolute path to the server root as specified in the Folder field of the Creating a PHP Debug Server Configuration dialog box.
    • For Inplace Server configurations no mappings are required because the local and remote paths are the same in this case.
  4. The Preview area shows the host/port and the path mappings retrieved from the chosen server access configuration (deployment configuration).

    When you choose the deployment configuration to use, the Absolute path on the server field shows relative paths mapped to the project files and folders in the chosen configuration, that is, paths to files and folders relative to the deployment root. As you specify the absolute path to the deployment root (the server root for FTP/SFTP/FTPS or the mounted folder), the contents of the field are updated automatically and finally the field shows absolute paths on the server.

Last modified: 29 November 2017

See Also