Prerequisites

Firstly, make sure you have Xdebug installed on your server, and that the following settings are specified in the Xdebug ini file:

zend_extension=xdebug.so

xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000

The next step, is to set and export a variable within your shell profile on the remote server. In the terminal window (already connected to your remote server) type:

If the server uses zsh:

$ vim ~/.zshrc

If the server uses bash:

$ vim ~/.bash_profile

And add this on a new line, anywhere in the file:

export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0"

And then, just type:

If the server uses zsh:

$ source ~/.zshrc

If the server uses bash:

$ source ~/.bash_profile

You will need to restart services such as Nginx, Apache and/or FPM on your server to apply these configuration changes.

Note that here we are using 127.0.0.1. It’s fine, later on we will use an SSH tunnel to redirect the traffic from port 9000.

Configuring PHPStorm

Creating a new empty project

Now we will need to configure some bits in PHPStorm. First of all we will need to create a new empty PHP project. In this new project, we will need to use the remote CLI interpreter on the server. Click on the ... as it is shown in the following screenshot:

In the Default CLI Interpreters window, click on the + button:

Then you will be greeted with some options. We will need to select the Remote... option:

In the Configure Remote PHP Interpreter window, select the SSH Credentials option, and fill the blanks as it is shown below:

Now, your Default CLI Interpreters configuration should look like this:

We then click on the OK button in the right-hand bottom corner, and our New Project window should look like this:

Finally, click on the Create button.

Deployment & Mapping configuration

Now we need to setup our deployment and mapping configurations. To do this, we need to open the PHPStorm preferences and go to Build, Execution, Deployment > Deployment, and click on the + button as it is shown in the screenshot below:

This will open the Add Server window. Specify a relevant name, and set the type option to SFTP. After this, click on the OK button.

With this complete, we will click on the icon to set it as a default deployment server for this project. Then the name of the server will be shown in bold:

We then need to configure the connection as follows:

The next step is to configure the mappings. Click on the Mappings tab, and fill in the blanks like so:

Now, in the PHPStorm preferences, go to Build, Execution, Deployment > Deployment > Options, and select the option On explicit save action. This will upload the given file to the server after explicitly saving it.

Click on the OK button and go to the Project View. Right-click on the project root folder and select the option Deployment > Download from PotatoServer:

You will find that the files hosted within the deployment path on server are now copied into the local path we specified.

Now, if you modify a file and save it, you will see that a new panel will appear with the file transfer information.

Note that we need to explicitly save the file in order to upload it to the server.

Debugging

Open an SSH tunnel

Now that we have everything configured, we will need to open a SSH tunnel and set up port forwarding for port 9000 (or the one specified in the xdebug.ini file) to connect to your remote server. You will need to have this tunnel open in order to debug with PHPStorm.

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.

Remote debugging in PhpStorm via SSH tunnel

To do this, we will need to type the following into the terminal:

$ ssh -R 9000:localhost:9000 username@remote_server_host -p remote_ssh_port

When this has successfully connected, you do not need to do anything else, just leave the SSH tunnel open.

Listen for PHP debug connections

Now we need to start listening for PHP debug connections in PHPStorm, to do so click on the phone icon and turn it on .

Hit the breakpoint

Place a breakpoint in your code, in a place you know for sure will be executed.

You will notice that PHPStorm will prompt us with an incoming connection dialog that we need to accept before carry on. This normally only happens the first time after setting up the configuration.

Using it within Chrome

Install the Xdebug helper extension for Chrome.

Once installed, click on the bug button and select the Debug option from the drop-down, then the icon will turn green. Access the page you want to debug and the execution will stop at the specified breakpoint. Select the Disable option to turn it off, to stop debugging.

Using it within Firefox

Install The easiest Xdebug extension for Firefox.

Once installed, click on the bug button , then the icon will turn green. Access the page you want to debug and the execution will stop at the specified breakpoint. Turn it off to stop debugging.

Using the command line

Connect via SSH to your remote server (you can use the already open connection used for the tunnel), and execute the script.

And that’s it, Happy debugging!