The definitive remote debug and unittest with PHPStorm guide: part 6

This post is part of the guide on how to setup your PHPStorm for remote debugging and unit testing. Click here for the beginning of this guide.

So there is already a lot covered: debugging web applications, testing your units, getting code coverage. But one thing that remains is trying to debug your command line applications. Even today more and more applications aren’t built for primarily the web, but for other purposes or many web frameworks have some kind of “console” component which allows you to easily create command line tools that deals with asynchronous handling of data, or just mere as cronjobs.

Debugging your command line applications

So this part is about trying to debug your command line applications. Even though internally it works the same way as debugging your web application, a few things must be done in order to get everything working.


Getting xdebug and phpstorm to play nicely on the command line, a few things must happen:

  • Xdebug must be active.
  • PHPStorm must be listening.
  • Xdebug must know where to connect to.
  • PHPStorm must know how to map paths and which project is incoming.

Xdebug must be active

We already done this by auto-enabling xdebug in its configuration. This is also true for command line applications, if you use the same configuration for both web and cli (and most of the time you will use the same config). You can check if xdebug is active on your command line by typing:

This displays a list of all modules currently active in PHP, and under the “zend extensions” you must see the Xdebug module. If not, xdebug might not be configured for your command line PHP (on some systems, the configuration for the commandline php and the webserver php differ).


PHPStorm must be listening

Obviously, phpstorm must be listening to incoming debug connections. This is simply done by toggling the “debug” icon in the toolbar in PHPStorm. By now you should be pretty familiar with this.


Xdebug must know where to connect to

Remember we are using the xdebug.remote_connect_back setting in our xdebug settings? This tells xdebug to connect back to the IP that is connecting to our website. Xdebug does this by looking at the $_SERVER variables (HTTP_X_FORWARDED_FOR, and if that does not exist, the REMOTE_ADDR variable). However, if you run a CLI application, those two variables are not available and thus xdebug has no way of knowing where to connect to. We can solve this in a few ways: first, we can change our xdebug configuration and add a xdebug.remote_host field which holds the IP of our local machine.

But a better solution (at least, i think), is to set this dynamically every time you run your cli app.

When we run this, xdebug knows it needs to connect to our local machine running at To make this a bit easier for you, you can create an alias for this:

All we need to do in order to debug our command line apps is:

Another way is to export these settings into an environment setting:

This will automatically be picked up by xdebug as well, and you can still run directly php (without the alias). Since we will be needing another export setting below, this solution might be the most elegant.


PHPStorm must know how to map paths and which project is incoming

One thing you will notice is that path mappings etc aren’t used anymore when it comes to CLI apps. The reason is simple: inside PHPStorm you have defined your server with a certain name and certain path mappings. When running from the command line, it cannot detect anymore which server you are running. This is also an easy fix. On your remote system, issue the following:

Xdebug sends over these environment variables to PHPStorm, and the IDE will automatically detect and use these variables when a debug connection is made, so it will know which server it needs.  After we have set this on the command line, we can easily debug command line apps the same way as our web apps. Just set the breakpoints and you’re done!



Almost there! In our last part we will discuss about how we debug our unit-tests. In the meantime, hope you enjoy this and the previous parts!

Joshua Thijssen is an all-round consultant and trainer. His daily work consists of maintaining code bases, working on different projects and helping other to achieve higher standards in both coding and thinking. He is author of the PHP|Architect book "Mastering the SPL library" and the Symfony Rainbow Series, founder of the Dutch Web Alliance and regular speaker at national and international conferences. Find him on twitter at @JayTaph, or read his personal blog at

Dutch Web Alliance