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. Note that enabling Xdebug may slow performance for the environments that it is enabled on.

If instead of debugging an Acquia environment you'd like to debug a local Acquia Dev Desktop environment, then please go to our article Using PhpStorm with Dev Desktop.

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.

• Create an SSH tunnel to your server. Documentation on finding ssh connection details is at Enabling SSH access. In general, from a command line on your local machine, you can either do this:

  ssh -R 9000:localhost:9000 username.env@server.prod.hosting.acquia.com 

• Or, you can add an entry to the ~/.ssh/config file on your local server, and then use the command ssh xdebug-dev from the command line.

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

• To confirm that the forwarding is in place, from the command line on your remote server, run netstat -nlt | grep 9000 (or whichever port you've configured) to verify that the server is listening.

Once this is 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.