Configure Debugging with PHPStorm

Debugging is crucial part in being productive developer. Setting up debugging for PHPStorm IDE has been a painful process partly because the info on the subject matter online have been confusing to say at least. In this post, I hope to clarify some of the misconceptions and, perhaps, save some of your time.

It’s important to note, you will not be able to do remote debugging if your PHPStorm IDE is on machine with dynamic IP and is behind LAN that you don’t have control of configuring the router because Apache server Xdebug service needs to forward requests to the PHPStorm IDE

The post is divided into two main parts – Configure Server and Configure PHPStorm IDE both of which needed to make debugging work in PHPStorm

Tested: PHP5.4.10, Mac OSx 10.7, PHPStorm 5.0.4

How it works?

(in general)
When you start debugging at PHPStorm IDE, then your PHPStorm IDE makes request to the Apache Server Xdebug service and goes into wait mode. Next, you make request from your choice of browser to your site. Apache server receives this requests and from the session forwards it to the Xdebug service part of Apache suite. The Xdebug service forwards the request to PHPStorm IDE that steps through your break points. After done stepping thought the code, PHPStorm IDE sends response to Apache server Xdebug service which forwards it to Apache and Apache responds to your browser. A real good description on how it works is listed at http://xdebug.org/docs/remote

Part I – Configure Server

On server, we have to enable Xdebug service to be loaded with Apache and then configure Xdebug to be able communicate with PHPStorm IDE.

1) Install Xdebug

For Mac:

sudo port install php54-xdebug
port activate php54-xdebug

For Ubuntu:

sudo apt-get install php5-xdebug

For windows:
In the php.ini file add the following:

extension="/path/to/xdebug.so"
2. Configure Xdebug

To configure Xdebug add the following in php.ini file:

[Xdebug]
zend_extension="/usr/lib/php5/20090626/xdebug.so"
xdebug.remote_enable=1
xdebug.remote_port=9123
xdebug.remote_host=localhost//or IP of your remote server
//xdebug.remote_connect_back=1
xdebug.remote_log = /Users/mkapacs/xdebug/xdebug.log
xdebug.idekey="PHPSTORM"

The above configurations:

  • ‘zend_extension’ ensures to load xdebug module with apache
  • remote_port(i.e. ‘9123’) is the port used in communication between apache xDebug service and PHPStorm IDE.
  • remote_host(i.e. localhost) is the IP of machine with PHPStorm IDE.
  • ‘remote_connect_back’ if it set to 1, then you don’t need the remote_host because xDebugger determines PHPStorm machine’s location from the initial PHPStorm request header. This is preferred way when your PHPStorm IDE is on machine with dynamic IP, so you don’t have to reconfigure remote_host every time new IP is issued
  • idekey(i.e.’PHPSTORM’) can be any string. It is used for identifying unique session

Restart apache to load the new configurations.

3. Test Xdebug

In older versions and setups of Apache, we could test whatever xdebug was loaded by running:
apachectl -t -D DUMP_MODULES
If no xdebug configurations shows up in the list then your xdebug modules is not loaded

Today, i check by looking to see if there is logs written in locations as specified in xdebug.remote_log. If nothing is written than xdebug does not load…or a wrong assumption!!! The Xdebug Manual states:

xdebug.remote_enable
Type: boolean, Default value: 0
This switch controls whether Xdebug should try to contact a debug client which is listening on the host and port as set with the settings xdebug.remote_host and xdebug.remote_port. If a connection can not be established the script will just continue as if this setting was 0.

This makes me think that in past i didn’t see the logs written not because xdebug module was not loading but because Xdebug wasn’t able to establish connection with PHPStorm IDE, so it continued without xdebug and without writing logs. I don’t know, but when that happened I often forced xdebug module to load till the logs came up.

Force Xdebug to load with Apache

So, when there is no Xdebug logs written in location as specified at xdebug.remote_log, I was under impression that xdebug.so module is not loaded with Apache. In the following are steps to make to load xdebug module to see the Xdebug logs.
For Apache2.4 and Ubuntu14, it is as easy as installing package containing xdebug

sudo apt-get install libwxbase2.8-dbg

This will configure and load xdebug for Apache. Xdebug logs should be written

For older version of Apache, add the following line to apache configuration file httpd.conf:
LoadModule xdebug_module libexec/apache2/xdebug.so

!!!Make sure you copy the ‘xdebug.so’ into /path/to/apache2/modules directory

If you don’t know the path to xdebug.so, then To find location of your xdebug.so:

find / -name 'xdebug.co'

In our case it was in ‘/usr/lib/php/extensions’ dir

Part II – Configure PHPStorm IDE

Configure PHPStorm IDE involves configuring server info, so PHPStorm IDE knows where to make the initial request and then specify the port on which to wait from Server to forward user request. At last, set up the debugging.

1. Provide Server Info

a) Open PHPStorm settings(command + ‘,’) and navigate to PHP->Servers. Add server as following:


The drupal.local can be the IP address of the Apache Server. The port can be 80 as well so you don’t have to configure extra port(i.e. 9001) for Apache to listen

2. Provide Port

The port(i.e remote_port) you specified in the php.ini for communicating with PHPStorm IDE should go here. Navigate to PHP->Debug and then enter port under Xdebug section as following:

3. Set Up Debugging

At last, set up the debugging in the PHPStorm IDE by going to RUN->Edit Configurations and Add ‘PHP Remote Debug’ as following:

4. Test Drive

Lets test it by initiating the debugging in PHPStorm IDE:

a) Set break points

b) Start debugging as following:

To validate it started, look for message as follows:

c) Open browser

  • Turn on session via PHPStorm Marklets
  • –OR–

  • append ‘?XDEBUG_SESSION_START=PHPSTORM’ to your url

Both do the same thing add session id to the request
It should stop at your break point

Other

Enhance with xdebug.remote_autostart=1

If you include the following setting in php.ini:

[Xdebug]
...
xdebug.remote_autostart=1

Then XDebuger starts automatically without need for session id be sent from browser. As long there is PHPStorm Xdebuger listener waiting the apache server will forward all requests to it automatically. Turn off the PHPStorm Xdebuger listener and apache server will not forward request instead process them.

Start Debugger from Command Line

To start debugger from command line, everything is the same as above described except you have to give id to the command shell:

export XDEBUG_CONFIG="idekey=PHPSTORM"

Now, start the debugger at PHPSTORm and run script such as Drush command. Is should break at your breakpoints.

Troubleshooting

1. xdebug logs not showing up

This means xdebug module is not loading for apache(this is not always true, please see above). Besides php5-xdebug & it’s configurations in php.ini, the apache itself needs to load xdebug module. For ubuntu, you have to install a separate package – that includes xdebug module as following:

 sudo apt-get install libwxbase2.8-dbg
 service apache2 restart

Now, you see the logs of xdebug to help troubleshoot further

2. Address already in use: make_sock: could not bind to address [::]:80

This error happens when it is declared apache to listen on port 80 two times. Make sure you don’t have specified ‘Listen 80’ in two places httpd.conf and httpd-vhost.conf.

3. Scripts Run from command line always breaks at first line

Its the PHPStorm debugger configuration that you can change by unchecking the ‘Force break at [..]’ PHP->Debug PHPStorm configurations in xDebug section

Remote address found, connecting to [..]Time-out connecting to client. :-(…Could not connect to client

This happens when the Apache server Xdebug service is forwarding request to the PHPStorm IDE but it doesn’t have static IP or it’s behind firewall, NAT or some other configurations that prevents the communication between server to client. You can verify it by telneting from your Apache server machine to your PHPSTorm IDE machine:

>telnet
>O
(to) IP.COMES.HERE PORT

Solution is to open the port in the firewall or configure IP accordingly to make PHPStorm reachable from server. For Mac, make sure the ‘Remote Login’ is enabled at ‘Preferences/Sharing’

Remote file [..] is not mapped to any file path in project

You have to map the directory of your project locally to the one at the server. This can be done by going to File -> Settings->PHP->Server.

It doesn’t break at my breakpoints

One possible problem is that you haven’t mapped all of the files to the ones on the remote server. As result, Xdebug service doesn’t forward execution to your PHPSTorm IDE files. Go to ‘Settings’->’PHP’->’Server’ and configure dir mappings for your debug server

Useful Links