How to setup local PHP debugging with PHPStorm and Xdebug

I am checking out a new IDE on the block – PHPStorm… well, new for me anyway :)

For Java and Python, Eclipse is all I need, but when coding in PHP, I am not a big IDE guy, for me, Vi is still the weapon of choice. But when it comes to debugging complex apps(yeah you can write those in PHP too :) , Vi doesn’t quite cut it. There are plugins for it to provide debugging capabilities(or rather Vimified interface to Xdebug), but half of the time it doesn’t work and the other half of the time it’s not what I am looking for. So far, I’ve been a user of Komodo IDE, I still have the old version 4 up and running here and do most of my debugging in it. It’s nice on one side, but somewhat cumbersome on the other.

Anyway, one major thing that always kept me from trying new IDEs is debugger setup. I tend to spend 10 minutes trying to setup debugging in new IDE, get frustrated, say fuck it, and get back to Komodo. This short blog post is to capture how I setup debugging in PHPStorm using Xdebug.
There is a video about this as to how to get a remote debugging working, but not much info about how to get a local one for folks who is on Linux(Ubuntu in my case).
So there we go:

Xdebug Setup

Step 0. Get phpize. If you’re on Ubuntu it’s as simple as running sudo apt-get install php5-dev
Step 1. Get Xdebug, it’s pure awesomeness. Just go here: and follow the instructions. Note: you can also try installing it from pecl or Ubuntu repository, but I had problems with these methods before.
Step 2. I recommend not to follow the last step of Xdebug install instructions where it says to add zend_extension line to the php.ini file. Cleaner way of enabling Xdebug and then configuring it is to add a file xdebug.ini to /etc/php5/conf.d/ folder with the following contents:

;xdebug configuration
zend_extension = /usr/lib/php5/20090626/
xdebug.remote_host =
xdebug.remote_enable = 1
xdebug.remote_port = 9000
xdebug.remote_handler = dbgp
xdebug.remote_mode = req

This xdebug.ini will be picked up by both CLI and Apache and makes it easier to control without messing with the central config file.
Once apache is restarted and xdebug succesfully loaded, time to look at phpStorm’s side.

Step 3. Get Xdebug helper extension for Chrome or similar for Firefox is very handy. Get one so you can enable/disable debugging sessions from the browser. Make sure you set it up such that is loads up on your local domain. For example, if your project runs on myproject.local, your setup will prob look like this:

PHPStorm Debugging Setup

This is a bit less straightforward, but here I go anyway. Here are my assumptions:
My project is running localy at http://myproject.local
It’s stored locally in /home/user/Projects/myproject/public ,which is also a DocumentRoot for myproject.local Vhost config in Apache. There are ‘library’ and ‘application’ folders outside of DocRoot however.

Step 1. In PHPStorm, setup path to web browser(File->Settings->Web Browsers). It actually detected all paths correctly except for Chrome, which I had to set manually(in my case it was in /usr/bin/google-chrome)

Step 2. Setup run configuration – Run->Edit Configurations. That screen is kinda odd, but here is how I got it going.
* Create new configuration, with type PHP on Server

* Create new server(click on the button next to “Server” dropdown). I picked server type “Local” and set webroot to “http://myproject.local“. On the “Mappings” tab I set local path to /home/user/Projects/myproject/public
* Save that server and select it in the Run Configurations
Ultimately my config looked as following:

This looks like it. Now opening up a file inside that project and ‘running’ it will actually bring up a new Chrome window with a page and put PHPStorm in listening mode on port 9000 for Xdebug connections. You’ll need to activate ‘Xdebug helper’ in that window, after that all interactions with the server will be intercepted by Xdebug and PHPStorm.

25 thoughts on “How to setup local PHP debugging with PHPStorm and Xdebug

  1. Thank you for a descriptive tutorial, your articles are always easy to read and understand :)

    Unfortunately, I couldn’t make debug work in my PHP storm 2.0, because some setting look different and it is not quite clear, how to set them. For example, there is no “PHP on server” in debug configuration. When creating a server, there is no “mappings” tab. I don’t know, maybe it’s because this is an unstable test build, but it’s sad :)

  2. Actually, I got it working after all. “PHP on server” in 2.0 is replaces by “PHP web application” and mappings are there, the just look different.

    Thank you for your article, I would like to translate it to Russian, if you don’t mind :)

  3. @IcePhoenix thanks for the article!
    @Konstantin do you have an English version of that article you modified for PHPStorm 2.0 and translated to Russian? That would be very helpful because Google’s translation (although not too bad for generic topics) it’s absolutely terrible for technical topics and makes it a real headache to follow technical explanations :)

    I was also wondering if those instructions would apply to users who (like myself) are trying to set up their debug environment on Mac OS X with local MAMP and a remote server on a cPanel account…

    Thanks again for the great article to both of you! ;D

    • Should work pretty much the same with MAMP. I have it on my mbp so I might give it a try in a bit and share my experience with it :)

      As to cPanel – unless that server is controlled by you, most likely you’ll face 2 issues:
      - most of shared hosters reside behind a firewall, so the block everything except for FTP(S),HTTP(S), SMTP and related ports and thus will probably have xdebug port blocked too
      - most likely they won’t have have xdebug installed in the first place, so you won’t be able to connect to the remote Apache instance.

  4. How can use PHPStrom on CentOS linux System?

    I have install all packages and setup on CentOS linux System but i am not able to use PHPStrom on my centOS linux machine.

    Please explain if any idea?

    Thank you advance.

  5. Many thanks to you. I’ve been trying to get a php debugger working for a while in three different IDEs. I’m using PHPStorm 2.0 now and just selected “PHP Web Application” instead of “PHP on Server” for the new configuration. It’s working great now. Saved me a lot of time.

  6. Hello Everyone!,

    Thank you for your tutorial, i am using PhpStorm and it’s worked for me. Very helpfuly.

    i am using DebianServer Apache2 and php with Xdebug.

  7. You rock! I was having quite a bit of trouble setting up Xdebug on PHPStorm (I’m using PHPStorm 4.0.1 on Ubuntu), but your tutorial had me up and running in no time! Thanks!

  8. Pingback: How to setup local PHP debugging with PHPStorm and Xdebug |Antarctic Nest of Icephoenix | Mubashshir

  9. Pingback: How to Set xdebug in Mac OS X with phpStorm and MAMP in 23 Easy Steps | ScorpioTek's Blog

  10. I can’t get the debugger to work because it stops at every Chrome Extension loaded in my browser. I can’t find any way to tell it to ignore all Chrome extensions and simply debug the PHP in the open file. :-(

  11. Pingback: Cpanel Enable Php Short Tags

  12. Pingback: linux-php-PhpStorm Xdebug | 大力水饺

  13. Pingback: How to setup local PHP debugging with PHPStorm and Xdebug |Antarctic Nest of Icephoenix – MUBASHSHIR ZAKIR

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>