Configuring PHP debugging in PhpStorm 2.0



In the previous post Zero-configuration debugging with XDebug and PhpStorm 2.0, we discussed setting up debugging automatically. This works perfectly in most cases. However, sometimes you may still need to configure debugging manually. In this article we will explain how to do it.

Server Configuration

First of all, add a new server configuration in the Project Settings | PHP | Servers (Picture 1).

Picture 1: Adding a server configuration

The right-hand pane shows an empty server configuration (Picture 2).

Picture 2: Empty server configuration

What does each field define?

  1. Name – a unique non-empty identifier.
  2. Host – the name of the host where the application is executed.
  3. Port – the port number.
  4. Debugger – the debugging engine installed on the host and integrated with the server.
  5. Use path mappings – select this check box if the server is remote or symlinks are used. We will consider this setting with more details later.

Picture 3: Example of server configuration

When do I need to set path mappings?

You need to use path mappings when the paths to the files processed by the server differ from the paths to the files in the project. This happens in the following cases:

  1. The server is remote and the project files are local copies of the originals.
  2. The files processed by the server and the files opened in the IDE are the same, but symlinks are used. Because the debugger resolves symlinks during a debugging session, you need to tell the IDE actual absolute physical paths to the files on the server.

If the files that the server processes are in the project and you are not using symlinks, clear the “Use path mappings” check box. In this case, the IDE will open files according to the paths received from the debugger.

How do I specify path mappings?

Path mappings are set through a TreeTable which is both a project tree and a table for specifying corresponding path.

Picture 4: Path mappings tree table

How do path mappings work?

A path mapping specified for a parent directory is automatically applied to all its subdirectories. If necessary, you can specify path mappings for any subdirectory or even file separately.

Let’s consider the example in Picture 4 above.

The root directory for files on the server is ‘/home/nnmatveev/www/htdocs‘.
The local copy of these files on the client machine is stored in the folder ‘C:projecthtdocs‘. Accordingly, we need to specify the following path mapping: ‘C:projecthtdocs’ <-> ‘/home/nnmatveev/www/htdocs’.

On the remote host, the ‘/home/nnmatveev/www/htdocs/wizard.php’ file is a symbolic link (symlink) for the ‘/home/nnmatveev/wizard.php‘ file. The debugger resolves symlinks, and, as soon as the IDE receives a message that tells it to stop in the file with the ‘/home/nnmatveev/wizard.php‘ path, we need to “prompt” the IDE about the location of the corresponding file ‘C:projecthtdocswizard.php‘ in the project.
To give this prompt, we just edit the table and add the following mapping: ‘C:projecthtdocswizard.php’ <-> ‘/home/nnmatveev/wizard.php‘.

Using the ‘Listen PHP Debug Connections’ Mode

When do I need to use the Listen PHP Debug Connections mode?

Use this mode when debugging Web-applications with the use of browser toolbar and bookmarklets, that is when your debugging session is controlled from the browser.

Switching to the Listen PHP Debug Connections mode

To activate the mode, click the  button on the toolbar or choose Run | Start Listen PHP Debug Connections on the main menu.

Picture 5: The mode is off

Picture 6: The mode is off

Picture 7: The mode is on

Debugging in the Listen PHP Debug connections mode

After you have activated the “Listen PHP Debug connections” mode, PhpStorm accepts any incoming connections from debugging engines received through the ports specified in the settings, see Picture 8.

Picture 8: Handling ports

You can specify the ports for the IDE to listen to by selecting and clearing the “Can accept external connections” check box next to the corresponding ports, see Picture 8.  However, in most cases you have no reason to do so.
Upon pressing clicking the “Listen PHP Debug connections” button, error messages may appear, as shows in Picture 9. These messages are shown when the corresponding port is already used by another application. Such conflicts arise, for example, when both Zend Studio and PhpStorm are running simultaneously.

Picture 9: “Cannot start … “ error message

When in the “Listen PHP Debug connections” mode, PhpStorm accepts any incoming connections from debugging engines. To detect the server from which a connection is received, PhpStorm calculates the values of the $_SERVER[‘SERVER_NAME’], $_SERVER[‘SERVER_PORT’],  and $_SERVER[‘REQUEST_URI’] variables.
After that, the IDE examines the server configurations defined in the PHP -> Servers page of the Settings dialog box and finds the corresponding configuration that meets the following criteria:
$_SERVER[‘SERVER_NAME’] == Host and $_SERVER[‘SERVER_PORT’] == Port.
If no server configuration that meets these criteria is found, the IDE applies a mechanism of automatic server configuration which is called “Zero-Configuration debugging”. Find more details on this method in Zero-Configuration debugging with PhpStorm 2.0.
To ignore connections received through unregistered server configurations and prevent automatic configuration, select the “Ignore external connections through unregistered server configurations” check box (Picture 10).

Picture 10: “Ignore external connections through unregistered server configurations” check box

When in the “Listen PHP Debug connections” mode, PhpStorm accepts any incoming connections from debugging engines, starts background debugging, and opens the Debug tool window  as soon as a breakpoint is reached. This may make you think that no debugging is performed at all. If the mappings are incorrect, breakpoints are not set, so you will never see the Debug tool window.
So if you have encountered such problem, you have to consider two possible reasons:  either no connections are received at all or the mappings are incorrect and therefore the breakpoints are not set.
To check whether connections are received:

  1. Clear the “Ignore external connections through unregistered server configurations” check box (the check box is cleared by default) (see Picture 10)
  2. Activate the “Break at the first line” settings of your debugging engine.
    • For Zend Debugger, this setting is specified through the browser extension.
    • For Xdebug, select the “Break at the first line (for external connections)” check box (Picture 11).

Picture 11: “Break at the first line(for external connections)” check box

If all the settings are correct, the IDE opens the Debug tool window and shows that the debugging engine has stopped at the first line to be executed.

Picture 12: Stop at the first line to be executed

Using the ‘PHP Web Application’ Run Configuration

When do I need to use the ‘PHP Web Application’ run configuration?

Use this mode when debugging Web-applications in the browser without using any means of control over the session. The session is started from the IDE.

Picture 13: Creating a new “PHP Web Application” configuration

Picture 14: “PHP Web Application” run configuration settings

This run configuration will open the specified URL address in the browser. The URL address will be expanded with the required GET parameters for activating the debugging engine. These parameters depend on the debugging engine used, which is specified in the server configuration.
If the value of the ‘Start URL’ text box starts with a slash ( /), the final URL will be composed relative to the server host name specified in the run configuration, otherwise the URL address will be used as is
(Picture 13). This lets you debug Web applications with URL addresses containing the https protocol.

Picture 13: Arbitrary start URL address

Picture 14: Additional GET parameters for activating the debugging engine

Using the ‘PHP Remote Debug’ Run Configuration

When do I need to use the ‘PHP Remote Debug’ run configuration?

This run configuration is absolutely universal and can be used whenever other approaches are not applicable for some reasons. However, in the vast majority of cases, using the “Listen PHP Debug Connections” mode is much more convenient.

Picture 15: “PHP Remote Debug” run configuration settings

When a debugging session is launched with this run configuration, the IDE awaits connections with the specified ide key (or session id). During the session, the mappings specified in the chosen server configuration will be used.

Comments below can no longer be edited.

12 Responses to Configuring PHP debugging in PhpStorm 2.0

  1. MaziLLa says:

    March 11, 2011

    Thanks for the good post! But there is one question. What about the “path mappings” while using the “PHP Script” run configuration? Here is the real example:

    – our real project path on FS is “/www/vhost/r-125-x/”,
    – but we have symlink “/www/vhost/test” -> “/www/vhost/r-125-x/”,
    – in PhpStorm I have created IDE project using the symlink “/www/vhost/test” (Open Directory “/www/vhost/test”).

    When I run any console script from IDE (for example /www/vhost/test/cron/blaBlaBla.php), PhpStorm resolve the paths and open all files using the “/www/vhost/r-125-x/” path prefix instead the “/www/vhost/test/”. Breakpoins for the “/www/vhost/test/” do not work, of course.

    What you can advise in this case? Where can I do the “path mappings” while using the “PHP Script” run configuration?

  2. Nikolay Matveev says:

    March 11, 2011

    We have means to work with symlinks in ‘PHP Script’, but looks like there is a bug in your case. Please create a bug-report –

    Thank you for feedback!

  3. InnovativePhp says:

    April 20, 2011

    nice article keep posting good stuff

  4. Alex says:

    July 7, 2011

    Sorry, but as a bit of a beginner, I find this as clear as mud!

    I’m used to debugging web apps with PHPStorm 1.x and xDebug. What I want to try now is running PHP scripts with debug facilities. Is there a simple guide to doing just that (I feel that this article is far more wide-ranging than my needs!)

  5. Nikolay Matveev says:

    July 11, 2011

    Hello Alex,

    Sorry for delay. Do you still have the issue?
    Please describe your problem in our community forum –


  6. PHP Web Development says:

    July 18, 2011

    I didn’t knew how did MApping worked ..Thanks for providing me this informaion.

  7. docfish says:

    September 27, 2011

    I try to debug my php code, but get the message “Debug connection with Zend Debugger was not established”

    • nnmatveev says:

      October 6, 2011

      What do you want to debug – CLI scripts or scripts running on server?

  8. marco says:

    September 29, 2011

    i do not get this
    server is mapped as network drive so phpstorm downlaods all file to localhost.
    i set up the server port 9000 ad remote ip etc. nothing

    if i hit run he complains about “Php ececutable not found”

  9. dani says:

    November 30, 2011

    It don’t work in phpstorm! 🙁
    I use zendServer Version 5.5.0 with Zend Debugger v5.3 which is activated.
    phpStorm (2.x and 3.0) is php debug session listen activated (stat is green), breakpoint is set, but no response! 🙁

    Any idea, help, please?