Remote debugging Magento with Xdebug and PHPStorm

A while ago someone recommended me using Xdebug with my PHPStorm IDE to debug Magento applications. It’s incredible how timesaving it is, that is why I decided to share with you how to install and configure Xdebug to remotely debug Magento installation with PHPStorm.

1. Install Xdebug

Log into your remote server and install the xDebug extension. I have done this on an Ubuntu server so I used the following command:

sudo apt-get install php5-xdebug

On CentOS use:

yum install php-pecl-xdebug

Note the location of xdebug. You will need it on the next step. Now, to make sure the extension is loaded by PHP, go and edit the php.ini file and add the following lines:

; If you only provide the name of the extension, PHP will
; look for it in its default extension directory.
zend_extension=xdebug_module_path_goes_here
 
[xdebug]
xdebug.remote_autostart=0
xdebug.remote_enable=1
xdebug.remote_port=9000
xdebug.remote_connect_back=0
xdebug.remote_handler=dbgp
xdebug.remote_host=127.0.0.1
xdebug.remote_log = 1

Make sure to change the path to xdebug.so with the one you got from the installation. Now go ahead and restart Apache or PHP-FPM. To be sure that all went ok, use phpinfo() to check if the extension is loaded.

2. Configure PHPStorm

The next thing to do after you have the Xdebug loaded into PHP is to configure PHPStorm to listen and respond to the incoming Xdebug requests.

Go to Run -> Edit Configurations and create a new PHP Remote Debug configuration. Fill in a name for your configuration and choose your server if you previously created it. Also set the session key.

When creating your server enter your specific details for host, port and choose Xdebug as debugger. Make sure also that you check the “Use path mappings” checkbox and fill in your mappings.

At this moment PHPStorm can use your debug configuration.

3. Create the SSH tunnel to the remote server

Because in this example we are doing a remote debugging we need to create an SSH tunnel to the remote server. What you need to do is to run the following command from your local machine. A thorough explanation of the process you can read it here.

To create the SSH tunnel use the command:

 ssh -R 9000:localhost:9000 username_goes_here@hostname_goes_here

4. Install Xdebug helper

Because for each request I want to debug I need to use the parameter ?XDEBUG_SESSION_START=PHPSTORM I installed a chrome extension that I find it very useful and I share it with you. You can find the extension here and can be easily configured for PHPStorm.

5. Debug

First start the SSH tunnel, then go to Run -> Debug and choose your debug configuration. A debug window will open at the bottom of PHPStorm. In the Console tab of this window the message is displayed “Waiting for incoming connection with ide key PHPSTORM”

In your code, create a break point by clicking on the right side of the line number, and a red dot appears. Also make sure your Chrome debug extension is enabled or that you are sending the XDEBUG_SESSION_START parameter in the request.

Now you can easily debug your Magento application.

If you find this tutorial helpful please share it with someone who might need it. If you stumble in the process write in the comments bellow and I will try to help you. Also bellow you can find other resources about this topic.

Resources

Remote debugging in PhpStorm via SSH tunnel

Setting Up XDebug With PHPStorm

Debugging with Xdebug, PHPStorm, Magento, and Vagrant

Magento debugging hints