How does Xdebug know about breakpoints in an IDE?

Question

I am a big proponent of Xdebug and love PhpStorm. I have worked with many different setups for local environments and configuration seems to be a bit different each time.

My current environment is a docker container running on my local machine. I understand that PhpStorm is listening to 0.0.0.0, aka - to all network interfaces, and on a specified port (I'm using 9004). I also see that I can ping my local machine from the docker container hosting Xdebug.

What I don't understand is: when I put a breakpoint in PhpStorm, how does Xdebug know that it exists, so that when it hits that line of execution it should tell PhpStorm to stop?

Answer 1

When Xdebug first connects to the IDE, the IDE sends over a list of breakpoints that it wants Xdebug to interrupt PHP at. If you have a look at a log file (made with xdebug.log=/tmp/xdebug.log), then you will see commands being send starting with breakpoint_set. There is then a type (-t), often line for a file/line breakpoint, as well as the file name and line number.

When PHP runs code, Xdebug intercepts the execution, and when it sees a match filename/line number combination, it pauses the execution and goes into command mode so that the IDE can send commands to inspect the current scope (by sending content_get) as well as further information about variables (with property_get). Then when you click "Continue" or "Step Over", the IDE sends a command to Xdebug to do the equivalent action.

To see a full description of the protocol, give the DBGp protocol specification a read.