- 2. Setup an SSH tunnel to the remote machine
- 3. Debug!
- (optional) Debugging PHP CLI scripts with remote PHP interpreters or via SSH tunnel
1. Xdebug or Zend Debugger installed and configured
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.
Depending on our operating system and debugger we use, the setup will differ slightly. Let's see how we can do this.
To setup an SSH tunnel on Linux or Mac OS X, we can open a terminal and run the following command:
For Zend Debugger:
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.
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:
- Make sure Xdebug is configured to connect to 127.0.0.1 and port 9000. See #1. Xdebug or Zend Debugger installed and configured for a sample configuration.
- When using Zend Debugger, make sure the PhpStorm bookmarklets or Browser Debugging Extension is configured to connect to 127.0.0.1.
- Make sure PhpStorm is listening for incoming debugger connections prior to setting up the SSH tunnel.
- When a machine is rebooted or the connection is lost, the SSH tunnel has to be reestablished.
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.