--- title: "How to debug an Acquia Cloud environment using PhpStorm and Remote Xdebug" date: "2024-01-18T00:13:04+00:00" summary: image: type: "article" url: "/acquia-cloud-platform/help/93806-how-debug-acquia-cloud-environment-using-phpstorm-and-remote-xdebug" id: "7a87e8d6-68c2-46c0-a8a9-519209d31dac" --- This article will let you perform real-time debugging of an Acquia Cloud environment's code, using both the [PhpStorm IDE](https://www.jetbrains.com/phpstorm/) and the Remote [Xdebug](https://xdebug.org/) method. Before getting started with Remote [Xdebug](https://xdebug.org/) in Acquia Cloud, [contact Acquia Support](/service-offerings/contacting-acquia-support "Contacting 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.   **Note** This article assumes the version of Xdebug is **3.x**. For version 2.x see [https://xdebug.org/docs/upgrade\_guide](https://xdebug.org/docs/upgrade_guide). 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: ![PhpStorm Screenshot 1](https://acquia.widen.net/content/4f7ed053-7ac0-42be-a6a5-93002268d561/web/ka0Pb0000000OVN00N6g00000VCdgi0EM6g000002WBZq.png) * 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. ![PhpStorm Screenshot 2](https://acquia.widen.net/content/2f561f33-9f31-4f12-9a76-68df3fcf813e/web/ka0Pb0000000OVN00N6g00000VCdgi0EM6g000002WBa0.png)   **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](https://docs.acquia.com/cloud-platform/manage/ssh/enable/). In general, you can use perform one of the following options from a command line on your local machine: * **Option 1: Using the ssh command** ssh -R 9003:localhost:9003 username.env@server.prod.hosting.acquia.com * **Option 2: Using the ssh configuration** 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 9003 localhost:9003 * Next, verify that the SSH tunnel forwarding is in place, by verifying that the server is listening. Run the following from the command line on your remote server (this only works on Acquia Cloud Classic, there is no equivalent on Acquia Cloud Next):  netstat -nlt | grep 9003  (replace the port "`9003`" with whichever port you've configured) The output from this command shows the listening service ending with `: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](https://www.jetbrains.com/phpstorm/marklets/) to enable/disable this cookie. For more information, you can visit [Zero-Configuration Debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) 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 username.env@server.prod.hosting.acquia.com  **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 **Note** Make sure to remove this change when you are finished debugging.  **Third**, configure our server in PHPStorm to use the non-standard port (`8080`) :   ![xdebug-php-storm.png](https://acquia.widen.net/content/d2aea657-7460-4ecb-94ab-d815bad3f8f6/web/ka0Pb0000000OVN00N6g00000VCdgi0EMPb000001Rrvh.png)