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 reproduces only on a remote environment, such as an EC2 staging instance.

🔥 Caution

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

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 you are using a network router, configure port mapping to allow incoming connections to port 9000 and forward them to your localhost.

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

Setting up Xdebug on the EC2 instance and pointing PhpStorm’s Remote Debug configuration at it made it possible to set breakpoints and step through PHP code running on a remote staging server as if it were local. The pieces that actually make this work are the xdebug.idekey value matching the IDE key configured in PhpStorm’s server settings, and the absolute path mapping pointing at the exact web root on the EC2 instance. xdebug.remote_connect_back = 1 is what lets Xdebug find its way back to the IDE without hardcoding a local IP, which is convenient on a machine that moves between networks. If a breakpoint silently refuses to trigger, the path mapping is the first thing worth rechecking, and it’s worth turning xdebug.remote_autostart back off once the session is done rather than leaving it enabled indefinitely.