Zero-configuration debugging with XDebug and PhpStorm 2.0

This blog post is obsolete!
Please check new up-to-date tutorial on Zero-configuration Web Application Debugging with Xdebug and PhpStorm

Hello guys,
We have done a lot of work to simplify the debugging process in PhpStorm 2.0 and we are very grateful to our early adopters for their invaluable feedback. Let’s try a new debugging work flow in PhpStorm 2.0.

Installation of Xdebug

Make sure that you have installed Xdebug properly. Don’t forget to set the xdebug.remote_enable setting to 1. You can validate your installation using checker from

Prepare PhpStorm

Toggle the ‘PHP Listen debug connections’ button. Don’t use any run configurations.

Set a breakpoint.

Activate debugger on server

In order to activate the debugger you need to set the special GET/POST or COOKIE parameter (more details). You can do it manually, but it is much more convenient to use one of the special tools such as browser toolbars or bookmarklets for that.
Try our bookmarklets generator and get bookmarklets which will work in any modern browser and allow you to start/stop a debugging session by controlling the Xdebug cookie.

Start a debug session in browser.

Reload the current page.

Switch to PhpStorm and set the initial path mappings by selecting the path to the local copy of the script that we are debugging. These paths are similar if you are editing files directly on the server.

On reaching the breakpoint the debugger suspends. Now let’s investigate the application!


In some cases you may get an error message “Remote file path ‘path/to/script/on/server.php’ is not mapped to any file path in project“. This means that PhpStorm does not know which local file corresponds to the specified remote file path.

You can solve this problem quickly. Just click the ‘Edit path mappings’ link and set the necessary path mappings.

This blog is permanently closed.

For up-to-date information please follow to corresponding WebStorm blog or PhpStorm blog.

This entry was posted in Cool Feature, PhpStorm, Tutorial and tagged , , . Bookmark the permalink.

35 Responses to Zero-configuration debugging with XDebug and PhpStorm 2.0

  1. The bookmarket sets a session id of PHPSTORM, but PhpStorm is generating a new number each time, e.g., “Waiting for incoming connection with ide key ’10060′. So the two are not connecting. I’m looking for the place where I tell PhpStorm to use PHPSTORM instead of 10060. Thanks.

  2. Nikolay Matveev says:

    Hello Geoffrey,
    Looks like you are using ‘PHP Web Application’ run configuration for debugging. For zero-configuration debugging you just need to toogle listening button(red button with handset).

  3. Marcus Bointon says:

    I’ve had problems trying to get this working on MacOS X for ages, despite having xdebug set up apparently correctly. I finally got to the bottom of it: CheckPoint’s SecureClient VPN was using port 9000. Changing xdebug’s port number at both ends to something else (I used 9124) allowed it to work.

  4. Dmitry Dulepov says:

    I have troubles with debugging using zero configuration since 2.0 final. It worked ok in pre-final EAP. Now PhpStorm just does not see the debugger if I press “Listen” button. Here is XDebug log: What bothers me is “command not available”.

    If I start debugging manually from debugging config, it opens in the new browser window, stops on breakpoints, etc. Only zero configuration does not work for me.

  5. Nikolay Matveev says:

    Log looks OK. Probably execution never reach line 59 in “/Users/dima/Projects/My/t3trunk/typo3conf/ext/blog_example/Classes/Controller/BlogController.php” or file is located in symlinked folder

    Enable “break at the first line” for xdebug to check debug:
    Enable “PHP -> Debug -> Break at the first line(for external connections)” checkbox or use “xdebug Break On” bookmarklet from

  6. Keith Ivey says:

    I think you need more detail at the “set the initial path mappings” step. Where is that?

    Also, I’m surprised reloading the current page doesn’t have to come *after* setting up the path mappings, but I guess I’m misunderstanding how things work.

  7. Howard says:

    Does phpstorm support the ability to force a breakpoint that executes during runtime? PHPed has a “debugBreak();” function that you can insert into code and when that code is executed it automatically starts a debug session at that point in code. This is handy very handy in many situations.

  8. axolx says:

    I’m testing Phpstorm 2. While feature rich, I’ve ran into many things that don’t work or are involved to set up.

    Most importantly, debugging. I have not been able to successfully debug a Web app running on localhost. The debugger will not detect breakpoints on any included files beyond the main index.php. Looking through the forums I see lots of people having the same problems for several versions, but forums threads are noisy, refer to screens on different versions and OS’s. I could not find a definitive solution to the breakpoint problem flagged anywhere.

    It’s a bummer because the rest of the app is robust and I could see myself switching from Netbeans to Phpstorm, but the Netbeans debugger works very well out of the box.

  9. Nikolay Matveev says:

    It depends on debugger engine.
    XDebug have ‘xdebug_break()’ function, but call of this function just emulates breakpoint and will not automatically start debug session.
    Details –

  10. Nikolay Matveev says:

    @Keith Ivey
    You should set initial path mappings if server with such name/port is not registered in PhpStorm. After setting up server and path mappings, debug connections would accept without any dialogs.
    Please use forums for further discussion.

    We will try to clarify things in the next blog post.

  11. Nikolay Matveev says:

    For ‘localhost’(without symlinks) the setup is pretty easy. Just add new server to ‘PHP -> Servers’ and set ‘Debugger’ to ‘XDebug’ and use this server in run configurations.

    Do you have issues related to steps described in the blogpost?

  12. dsjm says:

    Same problem as axolx. I use localhost, note that debugging works with my parallel Netbeans installation.
    To be precise: debugging worked before binding Firefox in the IDE!

    I followed the steps described here and now
    1) the script is executed without stopping at the breakpoint
    2) In the Debug/Variables status windows none of the variables is shown, only the status “Connected”
    3) The debug buttons (Step over, step into, …) are grayed out, I can’t press them

    Please help, I’m currently evaluating the IDE

  13. David Raher says:

    Is there a way to setup PHPStorm to catch breaks when running a PHP script via command line (ie, not just browser)?

  14. Nikolay Matveev says:

    Yes, there is a way(currently it is kind of workaround). What debugger engine do you use – Xdebug or Zend Debugger?
    Please create a discussion thread for the further discussion here –
    Also please vote for the issue(zero config debugging for command line) –

  15. Nikolay Matveev says:

    Enable ‘break at the first line’ using ‘xdebug Break On’ and ‘xdebug Break Off’ bookmarklets from or enable checkbox ‘break at the first line(for external connections)’ in Project Settings -> PHP-> Debug. Then please report here about results.

  16. dsjm says:

    I enabled the checkbox, same problem.
    Thank you for helping, however my evaluation has ended.

  17. Nikolay Matveev says:

    \To be precise: debugging worked before binding Firefox in the IDE!
    Please elaborate
    Please create a discussion thread for the further discussion here –

  18. Henning says:

    I am developing within a CRM at the moment. Some of the php-files executed will never be within the project. Thus I am unable to setup the correct mappings. Any solutions to this? I would also very much like something equal to DebugBreak() for xdebug. Sometimes it’s very important that the script does not execute if a debug-session isn’t initialized.

  19. Nikolay Matveev says:

    Sorry for delay.

    \Some of the php-files executed will never be within the project
    Do you want to debug such files?

    \I would also very much like something equal to DebugBreak() for xdebug.
    See an answer for the comment –

  20. keven says:

    I always tell me “Debug connection was not established”
    Can you help me ?

  21. Nikolay Matveev says:

    This message appears when IDE doesn’t received connection from debugger. It usually means that your debugger installed wrong. What debugger engine do you use – Xdebug or Zend Debugger?

  22. Samuel says:

    It always tells me “Debug connection was not established”.
    I have Xdebug installed (when I paste php -i output into the xdebug website it replys with the following:
    Xdebug installed: 2.1.1
    Server API: Command Line Interface
    Windows: no
    Zend Server: no
    PHP Version: 5.3.4
    Zend API nr: 220090626
    PHP API nr: 20090626
    Debug Build: no
    Thread Safe Build: no
    Configuration File Path: /etc
    Configuration File: /private/etc/php.ini
    Extensions directory: /usr/lib/php/extensions/no-debug-non-zts-20090626)
    when I run “phpinfo()” in my browser Xdebug does not show?
    I am running MAMP pro (on mac obviously) which is running ‘php5.3.2′ but when I run “php -i” through ‘terminal app’ It states php version “php5.3.4″. Is this OK? what am I doing wrong?

  23. Nikolay Matveev says:

    Hello Samuel,

    Sorry for delay. Please verify your output using this instruction –
    Also you can find some useful information about debugging here –
    If the links above will not help you, please create a forum thread and we try to help you there –

    Thank you for feedback!

  24. Nikolay says:

    Thanks a lot for this article! It was really helpful.
    I think it’s worth mentioning that there exist Xdebug extensions for all popular browsers which can set required cookies in a single click without bookmarklets.
    They can be found under the link mentioned in the article. Here it is:

  25. David says:

    Thanks a lot for an awesome resource, you guys rock at JetBrains, best IDE experiences ever!

  26. Jim says:

    Where can I find complete instructions on using Remote Debugging in PHPStorm 3.0+ ????

  27. Jim says:

    Does anyone know where the PHPStorm 3.0 version of this page can be found?

  28. Ofer says:

    I was so frustrated after spending so much time trying to configure the debugger to run on all my projects.. this solved everything! Thank you so much!!

  29. I am evaluating PhpStorm 3.0.3 on Windows 7 with a local Apache server and it took me hours to get the debugger working. First, I consulted the help pages of PhpStorm, then I found this article. But no success. One confusing thing about this article here is that it refers to a window called “Incoming debugger connection”. I couldn’t find such a window in PhpStorm 3.0.3….

    I finally got the debugger working with the help of this article here:


  30. Michael Pelz-Sherman says:

    Hi guys,

    This feature seems to have stopped working for me. I’m not sure exactly when, but it seems like a few updates ago. I’ve tried everything I can think of but can’t get it working correctly. I’m using Xdebug, running a remote server under VMWare on Mac OS X. I can get PHPStorm to break at the first line, but it doesn’t stop at my breakpoints. Any suggestions?

  31. Michael Pelz-Sherman says:

    Hey, it’s me again. :-)

    Just wanted to share a solution that worked for me. I went into the Edit Configurations dialog and created a new PHP Remote Debug configuration. Then I clicked on the “debug” icon, and the debugger window appeared with the message “waiting for incoming connection with ide key PHPSTORM”. Now when I submit a request to the server, PHPStorm breaks at the desired place again. I did not have to do this until some recent upgrade; not sure which one because I haven’t used the feature in a while.

    Anyway, hope this helps someone.

  32. 荒野无灯 says:

    Wow,the bookmarklets generator is really awesome~~~
    Thanks jetbrains ~~

Comments are closed.