The Power of Remote Debugging for Developers

Mastering Remote Debugging in PHP with Xdebug and PHPStorm

PHP Remote Debugging

Welcome, fellow developers! Today, we will delve into the essential yet often overlooked tool in our developer toolbox — remote debugging.

Remote debugging is an integral aspect of development, particularly when our code doesn’t behave as expected on a server, despite performing well on our local machine.

Prerequisites:

1. A remote server with PHP installed
2. Xdebug installed on the remote server
3. PHP Storm installed on your local machine
4. SSH Connection to Your Remote Server

The Development Cycle and The Need for Remote Debugging

Typically, our development cycle follows a predictable path. We write and complete our code on our development machine, be it a laptop or PC, then proceed with our chosen deployment process. Our code is then deployed on a server using methods such as FTP or Git, or perhaps via GitHub actions, Continuous Integration (CI), and Continuous Delivery (CD).

However, occasionally, we encounter problems that only manifest on the server, be it a live production server, a pre-production server such as staging or demo servers, or any other server. These problems often can’t be reproduced locally, which is where the power of remote debugging comes into play.

Understanding Remote Debugging

Remote debugging allows us to use the debugging concepts we are familiar with but with our code situated on a remote server. This significantly speeds up the debugging process. However, it’s crucial to understand the distinction between local and remote debugging setups.

In a local setup, we work on our machine with an Integrated Development Environment (IDE) like PHP Storm or VS Code, and our PHP code and XDebug are also on our machine.

And You can check How Xdebug works to get more understanding of the cycle of your debugging from here

Unleashing the Power of Xdebug for PHP Debugging

In contrast, for remote debugging, our IDE remains on our machine, but our remote server hosts the PHP installation. Therefore, we need to install XDebug on the remote server, which could be a production, staging, or any other server.

Accessing the Server and Setting Up

To perform remote debugging, we need to access the server. The most common method is connecting via SSH, which allows us to interact with the server freely.

Create a tunnel between Your local machine and Your remote server

using SSH which you can build a tunnel between your local and your server

ssh -R [remote_bind_address:]port:host:hostport user@remote_server

Let’s break down the different components of the command:

• -R: This option specifies that reverse port forwarding should be used.
• [remote_bind_address:]port: Specifies the port on the remote server to listen on. If you specify a remote bind address, it will bind only to that specific address. Otherwise, it will listen on all network interfaces.
• host:hostport: Specifies the destination host and port on the local machine where the network traffic will be forwarded.
• user@remote_server: Specifies the username and hostname or IP address of the remote server.

So in our case, we can set the command like that

ssh -R 9003:localhost:9003 root@remote_ip_addess

After gaining access, the next step is to install XDebug on the server. This can be done through the same method as on our local machine, either using the Wizard or PECL.

With XDebug installed, we then need to configure it to interact with our local IDE. This involves setting the client as localhost and allowing the db gb protocol to communicate through port 9003.

[xdebug]
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.start_with_request=yes

Navigating the Server and Understanding Path Mapping

Now, you might be wondering where Xdebug is located. It’s on the remote server, where we’ve established a tunnel connection. This brings us to the crucial concept of path mapping.

When we attempt to debug, we quickly encounter a problem: our code isn’t on our local machine — it’s on the server. This is where path mapping comes in. It enables PHPStorm to understand which file on the server corresponds to which file on our local machine.

Path mapping allows us to start using all the step debugging capabilities. We can make PHPStorm understand that a specific file on the server represents a specific file on our local machine. We don’t have to specify the files; we can just establish path mapping in general.

For example, if our user directory on the server (let’s say /var/www/html) corresponds to the Xdebug-demo on our local machine, we can set up path mapping accordingly. We can establish that the public directory on our local machine represents the absolute path /var/www/html/public on the server.

With this setup, our local machine’s root directory (the Xdebug demo) corresponds to /var/www/html on the server.

Experiencing Debugging on a Remote Server

Once we’ve set up path mapping, we can see how debugging works on a remote server. When we refresh the PHPStorm interface, it alerts us of an incoming connection from Xdebug. We can accept this connection, and a debugging session begins. It’s crucial to remember that we’re debugging the code or environment on the remote server, not on our local machine.

We can set breakpoints and refresh our page, and the program will stop at the breakpoint, just as it would if we were working locally. However, all our configurations aren’t on our local machine; they’re on the remote server. This means dealing with configurations, environment variables, and database connections that are different from our local setup.

Bypassing Firewalls and Debugging Securely

A vital part of remote debugging is understanding how to bypass firewalls. This is where tunneling comes into play. Tunneling allows us to bypass a firewall, which is essential when debugging on a production server where we can’t disable the firewall.

For example, if we’re using ufw (Uncomplicated Firewall) on a Linux server, we can check its status with ufw status. To allow SSH, we can use ufw allow ssh and then enable the firewall with ufw enable.

The firewall, or ufw in our case, is currently active and has two essential ports: port 80, utilized by nginx, and port 22, used for SSH. These ports allow us to connect via SSH, which is crucial in our setup.

ufw status

Once the firewall is enabled, we can continue debugging without any issues, even though the firewall is active. For example, we can disable a debugging session and then start it again without problems.

Conclusion

In summary, this walkthrough has given you a brief introduction to performing remote debugging through PHPStorm and Xdebug. The steps we’ve discussed involve setting up a tunnel, understanding path mapping, and bypassing firewalls using SSH. With these tools, you can debug code on a remote server as if you’re working locally.