Configuring PHP debugging in PhpStorm 2.0
Introduction
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?
- Name – a unique non-empty identifier.
- Host – the name of the host where the application is executed.
- Port – the port number.
- Debugger – the debugging engine installed on the host and integrated with the server.
- 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:
- The server is remote and the project files are local copies of the originals.
- 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:
- Clear the “Ignore external connections through unregistered server configurations” check box (the check box is cleared by default) (see Picture 10)
- 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.
