Remote PHP Debugging with Xdebug + PHPStorm or VSCode on Cloudways

Here’s a quick breakdown of the steps required to debug a PHP site on a remote Cloudways server.

Step 1:

Enable xdebug for the whole Cloudways server:

Server » Settings & Packages » Advanced » XDEBUG: Enabled

Step 2:

For the specific application in Cloudways, add some PHP settings:

Application » Application Settings » PHP FPM Settings:

Step 3: Setup SSH config for an ssh tunnel to the server:

1. Edit ~/.ssh/config

Step 4 (PHPStorm):

Configure PHPStorm Preferences

1. PHP » Debug » Xdebug » Debug port = 9003
2. PHP » Debug » Xdebug — Check all four boxes:
   • Can accept external connections
   • Resolve breakpoint if it’s not available on the current line
   • Force break at first line when no path mapping specified
   • Force break at first line when a script is outside the project
3. You shouldn’t need to configure servers, PHP cli, deployment locations, or anything similar…

Try It

1. Start an SSH tunnel: ssh mhd1_xdebug
2. Drop a breakpoint in index.php (or whatever will surely execute)
3. Visit the site, then wait for PHPStorm to prompt you for which file to connect to. Choose accordingly. It should connect and pause. You only have to do this once; it’ll remember the settings and path mapping in PHP » Servers.

Step 4 (VSCode)

Configure VSCode Preferences

1. Install https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug
2. Click the Run and Debug sidebar icon (⌘⇧D)
3. SSH into the server to find the exact path to the root of the site (which should match the root of your repo locally, your workspace folder)
4. Add new configuration (you can disable the log option if things work well right away)

Try it

1. Start an SSH tunnel: ssh mhd1_xdebug
2. Click Listen for Xdebug in the Run and Debug screen
3. Drop a breakpoint in index.php (or whatever will surely execute)
4. Visit the site