How to debug an Acquia Cloud environment using PhpStorm and Remote Xdebug

This article will let you perform real-time debugging of an Acquia Cloud environment's code, using both the PhpStorm IDE and the Remote Xdebug method.

Before getting started with Remote Xdebug in Acquia Cloud, contact Acquia Support and request that Xdebug and Xdebug remote be enabled, and state which environments you'd like them enabled on. Be aware that enabling Xdebug may slow performance for the environments that it is enabled on.
 

Preparing to debug your codebase

Once you receive confirmation from the support team that both of these are enabled, complete the following steps to start remotely debugging your codebase.

• On PhpStorm, you should start by creating a project that has your codebase in it. This codebase should exactly match what you have currently deployed on your remote (Acquia-Hosted) server.
• Now, open the Preferences dialog and look for PHP > Servers. Configure it as shown on the screenshot below:

• Next, create a new debug configuration by clicking Run > edit configurations > + > PHP Web Application.
• In the Server field, select the server created in the previous step.

Note
The following steps assume you are using the default port for connection (9003). If you aren't running the default port, or you're not sure what port is configured, you can find out by using this code, from the UNIX command line, to find out:

for conf in `find /var/www/site-php -name php.ini 2>/dev/null`; do echo "--- Checking $conf ---"; php -c $conf -i 2>/dev/null | grep xdebug.client_port; echo; done

• Create an SSH tunnel to your server. Documentation on finding ssh connection details is at Enabling SSH access.

• Option 1: Using the ssh command

ssh -R 9003:localhost:9003 [email protected]

• Option 2: Using the ssh configuration

Host xdebug-dev
Hostname server.prod.hosting.acquia.com
User username
Port 22
ServerAliveInterval 60
IdentityFile ~/.ssh/id_rsa
RemoteForward 9003 localhost:9003

• Next, verify that the SSH tunnel forwarding is in place, by verifying that the server is listening.

netstat -nlt | grep 9003

Once these steps are complete, you may start using breakpoints and debugging. Discussing this is beyond the scope of this document; just remember you will need to:

• Enable PhpStorm to accept incoming XDebug connections
• And use your browser to visit your Acquia-hosted site you just configured in the steps above, while sending the required cookie that enables XDebug. You can use bookmarklets to enable/disable this cookie.

For more information, you can visit Zero-Configuration Debugging at the PhpStorm documentation site.

Note
You may have breakpoints triggered before reaching your docroot's codebase. This is normal; you may bypass these from the debugger by clicking Resume Program for PhpStorm and continuing onto your desired breakpoints. This breakpoint's error may resemble the following:

Remote file path '/mnt/www/site-scripts/prepend.php' is not mapped to any file path in project

Ensure requests route to the correct web server

If you have multiple web servers (this is true of Acquia Cloud Classic), then you need to ensure that requests are routed to the one that you have Xdebug set up on.

All Acquia Cloud environments have caching and some are powered by multiple web servers; this may result in requests not triggering Xdebug on the web server you’ve connected to. You can ensure your requests route to the same backend by additionally forwarding HTTP to the server. (We use the environment name “example” in these instructions.)

First, change the the SSH command we discussed previously to add a port forward for HTTP as well:

ssh -R 9003:localhost:9003 -L 127.0.0.1:8080:example.prod.acquia-sites.com:80 [email protected] 

Second, modify /etc/hosts on your local machine to use this port forward by adding the following line:

127.0.0.1       example.prod.acquia-sites.com

 Third, configure our server in PHPStorm to use the non-standard port (8080) :