Command-line XDebug on a remote server

sugarcrmdevelopers —  November 21, 2012 — 2 Comments

Right now, all my development work is on a server and my development suite (PHPStorm in this case) is on my Macbook Pro.  I can easily debug PHP though the web interface using XDebug but I could not debug command-line scripts the same way.  I am writing alot of PHPUnit tests, and running them through a web based interface was problematic or impossible.  I have to run them on my remote server because I am developing against DB2 which wont run on the Mac.  What I wanted was to be able to SSH into my remote server, enter a command like “php phpunit2.php /mdoules/Accounts/bigtest.php” and have it run that test and debug it locally on my mac.   In addition to simple debugging, using XDebug on my PHPUnit tests allowed me access to the profiler which helped me find a few tests that were wasting alot of time and memory.  So here is how it is done.

First on the development suite on the Mac I had to give the debugger a server name so that the remote server would have something to address.  I chose IBM_SFA as my server name, you can make it whatever you want.  So in PHPStorm (and I am sure that in Zend or Eclipse it pretty similar) you open then configuration window (The preferences window in Mac-ese) and fill in the Servers window



The “Name” is the server name you chose, it can be anything.  The “Host” is the address of the remote server, the “Port” is always 80 for me and the “Debugger” is XDebug in this case.  You then check the “Use Path Mappings” checkbox and fill in the “Absolute path on server” to be the full path to the files on your server on the right side and the local path on the left side.  And thats all you have to do on the development suite side.

On the server side you need to do several things.  First you have to set up xDebug in your php.ini to talk to a remote server.  If you have xDebug working already you probably can skip this step.

So this is my xdebug.ini (read in by the php.ini file)


xdebug.default_enable = 1
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = /var/www

the remote_host part is the important part, it should point back to your development machine.  There are a few other ways to do this, if yours is working then leave it alone. If you are currently using remote_connect_back in the INI file that is read by the CLI version of PHP then switch to the remote_host line instead, remote_connect_back makes no sense in the CLI world as there will not be a remote connection made.  If you are using 1 php.ini file for both web and CLI then you will have to split them back up and have a separate php.ini file for each.  Most of the times the two files are in separate directories like /etc/php5/apache2/php.ini file into /etc/php5/cli/php.ini.  Some tutorials say that you need remote_autostart enabled but I have never found that to be a fact.  I have it turned off and it still works.

Now you have to add two environment variables,

export PHP_IDE_CONFIG=”serverName=IBM_SFA”

make sure you use ‘serverName’ and not ‘servername’, I have seen it both ways on several websites and the lower case one does not work at all. To make these two exports permanent or at least easy to invoke you can either just make a bash script with the two exports in it and put it in your home directory, or you can add them to the bottom of you ~/.bash_profile.

After this you are all ready to go.

1) First, tell PHPStorm to start debugging by clicking on the ‘Listen” button

and then set a breakpoint in the script that you want to debug.

2) Then go to the command line on your server and run the PHP script

php phpunit2.php /mdoules/Accounts/bigtest.php

and in a second or two, PHPStorm will go into debug mode and stop at whatever breakpoint you set up

2 responses to Command-line XDebug on a remote server


    Just a heads-up: the settings thumbnail is busted. The image behind it is fine.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s