Skip to end of metadata
Go to start of metadata


How can we debug on a remote machine when there are firewalls sitting in between? What if there's a NAT router preventing direct connections? What if our ISP or network infrastructure does not allow incoming TCP connections to the developer machine? In this tutorial we'll see how we can use an SSH tunnel to setup a secure connection between our development machine and a remote server.


Be sure to check the other tutorials about debugging PHP code with PhpStorm to learn more.


1. Xdebug or Zend Debugger installed and configured

To debug PHP code with PhpStorm, we will need Xdebug or Zend Debugger with the remote PHP interpreter. Make sure either Xdebug or Zend Debugger are installed and configured with PhpStorm.

When using Xdebug, make sure at least the following settings are specified:

1. Listen for Incoming Debugger Connections

From the toolbar, toggle the “Listen debugger connections” button. We can also use the Run | Start Listening for PHP Debug Connections menu. Enabling this option will ensure PhpStorm reacts when a debugging session is started and opens the debug tool window for us.

Also make sure a breakpoint is set (or the Run | Break at first line in PHP scripts option is enabled). This is not strictly required, but t may help pausing script execution at a known location.

2. Setup an SSH tunnel to the remote machine

What we want to do is connect to the remote machine over SSH and setup port forwarding for port 9000 (Xdebug) or port 10137 (Zend Debugger). The idea is that we create a "virtual" TCP port on the remote server that sends its traffic to a TCP port on our own machine, tunneling traffic over SSH.


The SSH tunnel is used to connect through a firewall and setup a secure connection between the remote server and the developer machine. When the remote server can connect to the developer machine directly over (for example with a Vagrant machine), an SSH tunnel may not be needed.

In such case we have to make the debugger connect back to the developer machine IP address by setting xdebug.remote_host=ip_address_goes_here (Xdebug) or making sure the debug host is the IP address of the developer machine (Zend Debugger). This can be done using the PhpStorm bookmarklets, a Browser Debugging Extension or the techniques outlined in Debugging PHP CLI scripts with PhpStorm.

Depending on our operating system and debugger we use, the setup will differ slightly. Let's see how we can do this.

 Setting up an SSH tunnel on Linux or Mac OS X

To setup an SSH tunnel on Linux or Mac OS X, we can open a terminal and run the following command:

For Xdebug:

For Zend Debugger:

 Setting up an SSH tunnel on Windows

To setup an SSH tunnel on Windows, we'll need Putty on our machine. Once installed, we can configure the connection to the remote machine by providing the hostname and port.

Next, expand the Connection | SSH | Tunnels node on the left and add a new forwarded port.

  • The source port will be 9000 (Xdebug) or 10137 (Zend Debugger).
  • For destination, enter "localhost:9000" (Xdebug) or "localhost:10137" (Zend Debugger)

Make sure to select the "Remote" radio button and then click Add.

Click Open to connect to the remote server and setup the SSH tunnel.

Make sure that you are running a command to create an SSH tunnel from the developer's machine to the server (not vice versa).

When a machine is rebooted or the connection is lost, the SSH tunnel has to be reestablished.

3. Debug!

Once the SSH tunnel is up and running, we can start debugging using zero-configuration debugging with Xdebug or with Zend Debugger. When the debugger is started, PhpStorm will prompt us if we want to accept the incoming connection.

Once accepted, we will be able to debug using the techniques outlined in Using the PhpStorm Debugger.

(optional) Debugging PHP CLI scripts with remote PHP interpreters or via SSH tunnel

When the remote PHP interpreters are properly configured (with proper deployment mappings set in Settings / Preferences | Build, Execution, Deployment | Deployment or defined in .Vagrantfile), it's possible to configure run/debug configuration taking advantage of the remote PHP interpreter for debugging. Read more in working with Remote PHP Interpreters in PhpStorm tutorial.

When the SSH tunnel is up and running, we can also debug PHP CLI scripts. Since the debugger runs on a remote machine, starting a CLI debugging session can be done by using PHP command line switches or using environment variables (on the remote machine). Check Debugging PHP CLI scripts with PhpStorm for more information about how to debug PHP CLI scripts. This workflow is not officially recommended way of debugging, though it might be useful in some cases when the debugging session is needed to be established from the remote server side.


The debugger never connects or refuses the connection

When the debugger never connects or refuses the connection, check the following:

Remote file path is not mapped to any file path in project

In some cases, the debugger can connect but we get the error message "Remote file path 'path/to/script/on/the/server.php' is not mapped to any file path in project" or "The script 'path/to/script/on/the/server.php' is outside the project." This means that PhpStorm is not sure which local file corresponds to the file being debugged.

We can solve this problem quickly by clicking Click to set up path mappings and setting up the necessary path mappings.

Additionally, we can configure these mappings using the techniques outlined in Deploying PHP applications with PhpStorm.

  • No labels