How to Debug using Xdebug and PHPStorm from a Remote Server

I know what you’re thinking. Who in their right mind would want to develop using a remote server when you have Docker and all that other useful stuff? But, trust me, if you come into this unfortunate situation, you’ll be sending me all your love (or a beer, which is almost the same thing).


  • You need to check an issue in a PHP web application.
  • You are not allowed to run it locally.
  • You’ve got SSH access to the testing server.

Okay so you know what to do, right? Just install Xdebug in the server, set up your IDE and let the magic happen. Right? Sure, go do it and I’ll wait here while you figure it out.

So you’re back already, huh? I know why, because I too spent hours searching for documentation, blog posts, forums and some helped, but I couldn’t find a single one with all the information, so since I already did the research, here is all the info to save you and everyone else the trouble.

I won’t go trough the basics on how to use the debugger or about the magic behind the debug session (plenty of blog posts on this already).

You’ll need:

  1. A remote server (and SSH access to it)
  2. An IDE in your machine (I use PHPStorm)
  3. An issue you need to debug (d’oh!)

SSH to the remote server and install Xdebug

sudo apt-get install php5-xdebug (Debian based servers)

Configure Xdebug

The Xdebug configuration goes in the php.ini file (or in a specific .conf file inside your conf.d folder, it depends on the server’s OS)


Configure your IDE

As I said, I’m using PHPStorm, but any IDE configuration should be similar.

Go to Preferences -> Languages & frameworks -> PHP -> Debug

Go to Preferences -> Languages & frameworks -> PHP -> Servers

Name: Anything meaningful for you
Host: Server IP address
Port: The port used by Apache
Debugger: Select Xdebug
Check the “Use path mapping” option

Below, (I’m assuming you have the project code in your machine, we said you can’t run it locally, but you’ll still need the code) map the folders (paths) of the code in your local machine and the server.

Now, you’ll need a browser extension that helps you trigger the debugger (I use Xdebug helper for Chrome).

If you try to debug your application now, using the browser extension you’ll send a flag to the server and it’ll run Xdebug, tehn it’ll try to communicate with the address you configured in xdebug.remote_host, but it won’t make it since we configured it as localhost.

Then why did we configured it that way? Xdebug has the option to remote debugging, you could set your IP address there and voila! No, you couldn’t, at least not so easy. Because the server would try to reach your IP using the port 9000, and chances that your ISP has that port open are low.

You need an SSH Tunnel. Since you have SSH access to the server, you can create a tunneling protocol

ssh -R 9000:localhost:9000 your_user@your_server_host

Now your machine will be treated as localhost, and communication can happen without issues. You’ll have to open that tunnel every time you need to debug remotely to that server.

Happy debugging!

Do you need some help?

Let's get started. Tell us a little about yourself and your organization
and we can start a conversation about your needs and our capabilities.
Tagged: , , ,

Related Posts