Debugging PHP Remotely on AWS EC2 with PhpStorm and Xdebug

Remote debugging a PHP application on EC2 with PhpStorm and Xdebug, from the server-side ini settings to the IDE's path mapping.

Takahiro Iwasa

2017-07-16

3 min read

Remote debugging with PhpStorm and Xdebug is particularly useful when an issue occurs only in a remote environment, such as an EC2 staging instance.

🔥 Caution

Avoid debugging directly in production to prevent performance and security issues.

Architecture

The browser request travels from the developer machine to Apache and PHP on the EC2 instance. When PHP runs, Xdebug initiates a separate debug connection in the opposite direction: from EC2 to PhpStorm on TCP port 9000. If the developer machine is behind a router, that incoming connection must be forwarded to the machine running PhpStorm.

Remote debugging connection flow between a developer machine, a router, and an EC2 instance

Server Configuration

Add the following Xdebug settings to the php.ini file. The extension path shown here corresponds to PHP 7.1 via the Remi repository and should be adjusted to match the target environment.

1
[xdebug]
2
zend_extension="/opt/remi/php71/root/usr/lib64/php/modules/xdebug.so"
3
xdebug.remote_enable = 1
4
xdebug.remote_connect_back = 1
5
xdebug.remote_host = "127.0.0.1"
6
xdebug.idekey = "IDE_KEY"
7
xdebug.remote_autostart=true

Restart Apache to apply the change:

sudo service httpd restart

PhpStorm Configuration

Open Run > Edit Configurations... in PhpStorm, then select PHP Remote Debug.

Click Servers and add a target server with the following configuration:

Name: Remote host private IP
Host: Remote host public IP
Debugger: Xdebug
Use path mappings: ON
Absolute path: /var/www/html/<YOUR_WEB_APP_ROOT>

❗ Important

The path mapping must correspond exactly to the remote path. A mismatch allows the connection to succeed while preventing PhpStorm from stopping at breakpoints.

Set the IDE key you defined in the xdebug.idekey field of php.ini.

Port Forwarding

If your local machine is behind a network router, configure port forwarding to allow incoming connections on port 9000 and forward them to the local machine.

Debugging

To start debugging:

Place a breakpoint at the desired position in your PHP code.
Enable Listen for PHP Debug Connections mode in PhpStorm.
Access your remote server.

When the breakpoint is triggered, PhpStorm will pause execution, allowing you to inspect and debug the code.

Conclusion

With Xdebug installed on the EC2 instance and Remote Debug configured in PhpStorm, you can set breakpoints and step through PHP code on a remote staging server as though it were running locally. Two settings are essential: the xdebug.idekey value must match the IDE key configured in PhpStorm, and the absolute path mapping must point to the exact web root on the EC2 instance.

The xdebug.remote_connect_back = 1 setting allows Xdebug to connect to the IDE without a hard-coded local IP address, which is convenient when the development machine moves between networks.

If a breakpoint is not triggered, check the path mapping first. After the debugging session, disable xdebug.remote_autostart rather than leaving it enabled indefinitely.