Back to blog home

3 steps to set up CLI debugging with Xdebug in VM and PhpStorm IDE

Setting up Xdebug with PhpStorm is extremely simple when you have to develop for Web interfaces. When you have Xdebug running on a VM and you want to debug your scripts running on a CLI, the steps are slightly different. I tried following steps reading various blogs, but it was not very helpful to me. With the help of my colleague Mark Ross, I got this working. Then I took a step forward to write this blog, so I can share my knowledge with others.

Before explaining the setup process, I would like to explain how the systems interact, so you get a clear picture of what you are achieving in the next few steps.

Figure 1. shows a high level view of the setup in my Mac OSX Yosemite. My VM is running Centos 6.6 and I have Xdebug installed there. PhpStorm is installed in my OS X Yosemite.

The Figure 2. shows the interaction between PhpStorm and DGBP proxy server with Xdebug installed on my VM. The DGBP is a protocol that provides means of communication between a debugger engine and debugger IDE.


  1. The IDE sends proxyinit command with the port : 9000 that the DGBP proxy server needs to listen to along with IDE key “PHPSTORM”. The DGBP proxy server is now listening on port 9000.
  2. On execution of shell script in VM, the Xdebug engine communicates with proxy server located at the configured remote_host IP address and remote port number, with the ide key “PHPSTORM”.
  3. The proxy server then redirects the request to IDE, and the connection is established.
  4. Once debugging is completed, the IDE then sends proxystop command to request the DGBP server to stop listening on 9000 for IDE  key “PHPSTORM”.
  5. The connection is now aborted.

More information can be found in the Xdebug documentation. To get this up and running,  follow the three steps below:

1. Install and Configure Xdebug on your VM

  • Follow the instructions here to install Xdebug.
  • Edit the /etc/php.d/xdebug.ini as below:

xdebug.idekey = "PHPSTORM"
xdebug.remote_enable= 1
xdebug.remote_mode= req
xdebug.remote_host =
xdebug.remote_port= 9000
xdebug.remote_connect_back= 0 
#xdebug.remote_log = /var/log/xdebug.log
xdebug.remote_autostart= 1

  • zend_extension: Find the location of this extension file  in your VM and add it here.
  • idekey: This can be any value, but  bear in mind  that you should be using the same key at the Client Side, IDE .
  • remote_enable: You need to enable this for this case, as we are remotely debugging.
  • remote_mode: I am setting it to ‘req’ because I want xdebug to connect as soon my script is executed, but you can also have jit. For further info please refer to
  • remote host: You need retrieve the host ip address from your machine. Type ifconfig, look for  “vboxnet” instances like something below:

vboxnet1:flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST  > mtu 1500
ether 0a:00:27:00:00:01
inet netmask 0xffffff00 broadcast

  • remote_port: use default, ensure its the same at the client side, in this case your IDE.
  • remote_connect_back: It’s safe to set this 0. Otherwise it completely ignores the remote_host ip address and responds to any client requesting for a session, but please check this link for detailed information.
  • remote_log - this is very useful for debugging issues with your Xdebug configuration. You will only need to enable this if you are having problems getting Xdebug to work. Note that you will need to create the log file and make it writeable.
  • Please refer to autostart I am not sure how useful this is setting is with remote debugging.

The above are some basic settings. You could use advanced ones from under related settings.    

2. Set Remote Debugging Server in Client IDE: PhpStorm

  • Add new Debug Configuration: To do this, please click the dropdown beside the Bug Icon and select Edit Configuration.
  • Click ‘+’ and add new ‘PHP Remote Debug’.
  • Give it a name and click on server and add new Server, with the host being your VM’s ip address Port 80 and Debugger : Xdebug.
  • Use the same path mappings as Web Server. In my case I had to set  the project root directory to /vagrant/public, and click save.
  • Add your IDE key session, same as the one you used in the server side. In my case its “PHPSTORM”. Click Ok and save everything.

See the PhpStorm Documentation for more information.    

3. Start the remote debugging session from  PhpStorm

  • Once you have chosen the configuration which you just created, click on the bug icon.
  • The client is actively listening and you should see the message “Waiting for incoming connection with ide key "PHPSTORM". Now execute the script on the server, for example:  php test.php
  • You should be able to see the connection breaking at your first  breakpoint in the test.php file.

If you still have issues with setting up, you should be able to check the /var/log/xdebug.log file in the VM to figure out the cause. Good Luck!