- How does Xdebug work?
- 1. Run the DBGp proxy
- 2. Listen for incoming debugger connections
- 3. Start debugging from the browser
How does Xdebug work?
Debugging with Xdebug works in a very straightforward way. When we start a debugging session, for example using the PhpStorm bookmarklets or a Browser Debugging Extension, the PHP Xdebug extension makes a connection to the IP address and port specified in either the Xdebug configuration. The IDE then accepts this connection and can communicate with Xdebug over it.
Xdebug only supports connecting to one IP address, and does not automatically connect back to the IP address that runs the browser because of security reasons. We don't want everybody on the Internet to be able to run a debugging session against our code, do we?
So how to solve this? Well, we could have each developer update the PHP configuration with their IP address when they want to debug. But that's cumbersome and not very flexible. Fortunately for us, Xdebug supports a so-called DBGp proxy. With it, things change a little bit: the PHP Xdebug extension no longer connects to the IDE directly but instead connects to this one DBGp proxy server. All developers in the team then connect to that proxy as well. Each developer has a separate debugging session that runs over this proxy, making it possible to do multi-user debugging of the same code on the same server.
Let's see what we need to get this set up!
We'l need some things installed on our web server to be able to do multi-user debugging.
To do multi-user debugging of PHP code with PhpStorm, we will need Xdebug installed and configured on the web server. Refer to the Xdebug and make sure that at least the following settings are specified:
2. DBGp proxy
In order to be able to proxy the various debugging sessions, we'll need a DBGp proxy on a server that can be reached by the web server itself as well as all developer machines. We can install it on the web server, or on a machine in the same network (or with an SSH tunnel to the web server).
From the downloads page at Komodo, we can find the Python binaries of DBGp proxy for our platform.
Once downloaded, we can run
pydbgpproxy.exe, which we'll do right now.
1. Run the DBGp proxy
We will have to start the DBGp proxy either on the web server or on a machine that can communicate with the web server and all developer machines. The DBGp proxy executable accepts two switches,
-i, that tell the tool on which IP address and port to listen for debugger connections from the web server and on which IP address and port to listen for developers.
Here's an example that listens for debugger connections on the loopback address (127.0.0.1) and port 9000, and listens for developers on the machine IP address and port 9001.
Once running, the DBGp proxy will confirm these settings:
2. Listen for incoming debugger connections
From the toolbar, toggle the “Listen debugger connections” button (or use the Run | Start Listening for PHP Debug Connections menu). This will ensure PhpStorm reacts when a debugging session is started in our application.
We also have to register with the DBGp proxy server using the Tools | DBGp Proxy | Register IDE menu.
This will prompt us for details to connect to the DBGp proxy. Note that once configured, we can change this information using the Tools | DBGp Proxy | Configuration... menu.
We will have to enter:
- The IDE key to use. This should be a unique value for each developer, as it identifies the debugging session.
- The IP address and port of the DBGp proxy
After saving this information, the PhpStorm event log will tell us if the connection succeeded.
On the DBGp proxy, we can also see a connection from an IDE has been made.
3. Start debugging from the browser
Using the PhpStorm bookmarklets or a Browser Debugging Extension, we can start a debugging session. It's important to configure the correct IDE key. For example if in the previous step the IDE key "Maarten" was chosen, we should also configure the bookmarklet or the browser debugging extension to use that key.
After refreshing the browser window, PhpStorm will pause execution at the first breakpoint.
Remote file path is not mapped to any file path in project
In some cases, we may get the error message "Remote file path 'path/to/script/on/the/server.php' is not mapped to any file path in project" or "The script 'path/to/script/on/the/server.php' is outside the project." This means that PhpStorm is not sure which local file corresponds to the file being debugged.
We can solve this problem quickly by clicking Click to set up path mappings and setting up the necessary path mappings.
No connection could be made because the target machine actively refused it
There are several causes for this error. Check the following:
- Is PhpStorm listening for incoming debugger connections? Has it been registered with the DBGp proxy? Check #2. Listen for incoming debugger connections and make sure all steps are executed.
- Is the correct IDE key set in PhpStorm and in the debugger bookmarklet or browser extension? Check #2. Listen for incoming debugger connections and #3. Start debugging from the browser and make sure all steps are executed.
- Is there a firewall blocking connections to the DBGp proxy? If so, make sure the PHP Xdebug extension can connect to it, as well as the developer machines. You can use canyouseeme.org or similar service to check for opened inbound ports.
- Is there a firewall blocking connections to the IDE? Make sure that PhpStorm can be connected to from the DBGp proxy machine. You can use canyouseeme.org or similar service to check for opened inbound ports.
- The DBGp proxy binds to the wrong IP address. Run it using 0.0.0.0 as the address so it binds to any IP address on the DBGp proxy server. For example, run
pydbgpproxy -i 0.0.0.0:9001 -d 0.0.0.0:9000.
When testing multi-user debugging in PhpStorm with Xdebug and DBGp proxy on one machine, for example when trying out the steps outlined in this tutorial, there are some additional things to verify:
- PhpStorm binds to the wrong IP address. When DBGp proxy runs on a local machine where PhpStorm is also being run, the IDE may be using the wrong network subnet. To overcome this, use the Tools | DBGp Proxy | Configuration... menu and set the IP address of the DBGp proxy server to 0.0.0.0 and try re-registering the IDE with the DBGp proxy.
- A port conflict exists. When testing DBGp on a local machine, both PhpStorm and DBGp may want to bind to the same port. Make sure this is not the case, by either configuring DBGp to use a different port or by setting PhpStorm's Xdebug port from the settings / preferences (under Languages & Frameworks | PHP | Debug).