Features PhpStorm Tutorials

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 xdebug.org

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.

Comments below can no longer be edited.

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

  1. Avatar

    Geoffrey Knauth says:

    February 15, 2011

    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. Avatar

    Nikolay Matveev says:

    February 15, 2011

    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. Avatar

    Marcus Bointon says:

    February 16, 2011

    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. Avatar

    Dmitry Dulepov says:

    February 21, 2011

    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: http://pastebin.com/mwWkeeLz 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. Avatar

    Nikolay Matveev says:

    February 21, 2011

    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 http://www.jetbrains.com/phpstorm/marklets/

  6. Avatar

    Keith Ivey says:

    February 23, 2011

    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. Avatar

    Howard says:

    February 23, 2011

    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. Avatar

    axolx says:

    February 23, 2011

    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. Avatar

    Nikolay Matveev says:

    February 24, 2011

    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 – http://www.xdebug.org/docs/remote

  10. Avatar

    Nikolay Matveev says:

    February 25, 2011

    @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 http://devnet.jetbrains.net/community/wi?view=discussions for further discussion.

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

  11. Avatar

    Nikolay Matveev says:

    February 25, 2011

    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. Avatar

    dsjm says:

    March 15, 2011

    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. Avatar

    David Raher says:

    March 15, 2011

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

  14. Avatar

    Nikolay Matveev says:

    March 15, 2011

    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 – http://devnet.jetbrains.net/community/wi
    Also please vote for the issue(zero config debugging for command line) – http://youtrack.jetbrains.net/issue/WI-5132

  15. Avatar

    Nikolay Matveev says:

    March 15, 2011

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

  16. Avatar

    dsjm says:

    March 16, 2011

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

  17. Avatar

    Nikolay Matveev says:

    March 17, 2011

    \To be precise: debugging worked before binding Firefox in the IDE!
    Please elaborate
    Please create a discussion thread for the further discussion here – http://devnet.jetbrains.net/community/wi

  18. Avatar

    Henning says:

    April 6, 2011

    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. Avatar

    Nikolay Matveev says:

    April 15, 2011

    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 – http://blogs.jetbrains.com/webide/2011/02/zero-configuration-debugging-with-xdebug-and-phpstorm-2-0/#comment-5947

  20. Avatar

    keven says:

    April 19, 2011

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

  21. Avatar

    Nikolay Matveev says:

    April 19, 2011

    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. Avatar

    Samuel says:

    April 30, 2011

    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. Avatar

    Nikolay Matveev says:

    May 5, 2011

    Hello Samuel,

    Sorry for delay. Please verify your output using this instruction – http://xdebug.org/find-binary.php.
    Also you can find some useful information about debugging here – http://confluence.jetbrains.net/display/WI/Documentation
    If the links above will not help you, please create a forum thread and we try to help you there – http://devnet.jetbrains.net/community/wi

    Thank you for feedback!

  24. Avatar

    Nikolay says:

    October 19, 2011

    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: http://xdebug.org/docs/remote#starting

  25. Avatar

    David says:

    January 13, 2012

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

  26. Avatar

    Jim says:

    February 18, 2012

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

  27. Avatar

    Jim says:

    February 18, 2012

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

    • Avatar

      nnmatveev says:

      February 20, 2012

      This is still actual for PhpStorm 3.0. Do you have an issue?

  28. Avatar

    Ofer says:

    February 19, 2012

    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. Avatar

    Gabriel Sidler says:

    March 6, 2012

    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. Avatar

    Michael Pelz-Sherman says:

    March 16, 2012

    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?

    • Avatar

      nnmatveev says:

      March 19, 2012

      It is path mappings related problem. Please submit a new thread on our discussion forum if you want to resolve your issue completely – http://devnet.jetbrains.net/community/wi

  31. Avatar

    Michael Pelz-Sherman says:

    March 16, 2012

    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.

    • Avatar

      nnmatveev says:

      March 19, 2012

      Thanks for sharing!

  32. Avatar

    荒野无灯 says:

    April 9, 2012

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

Discover more