Understanding XDebug using Message Sequence Charts (mscgen)

These Message Sequence charts will help us to better understand the communication that happens between the IDE and XDebug during a debugging session. These charts are generated using the awesome mscgen_js library.

Single User/Static IP

  1. IDE/Editor starts a debug client server on PORT 9000
  2. User sends session initiation command to the XDebug using GET/POST/COOKIE parameters or environment variables
  3. XDebug connects to remote IDE using xdebug.remote_host and xdebug.remote_port values. It sends an init packet and waits without executing any code.
  4. IDE negotiates features or set any breakpoints
  5. IDE send commands to interactively walk through the code
  6. When finished, XDebug sends response back to browser.

Multi User/Unknown IP

  1. IDE/Editor starts a debug client server on PORT 9000
  2. User sends session initiation command to the XDebug using GET/POST/COOKIE parameters
  3. XDebug connects to remote IDE using $_SERVER['HTTP_X_FORWARDED_FOR'] or $_SERVER['REMOTE_ADDR'] values. It sends an init packet and waits without executing any code.
  4. IDE negotiates features or set any breakpoints
  5. IDE send commands to interactively walk through the code
  6. When finished, XDebug sends response back to browser.

DBGp Proxy

  1. IDE/Editor starts a debug client server on PORT 9002
  2. IDE sends a proxyinit command to the proxy server on port 9001 along with a idekey and an address to connect back to IDE on port 9002
  3. Proxy server stores the idekey and the IDE address where deubg clien is listening
  4. User sends session initiation command to the XDebug using GET/POST/COOKIE parameters
  5. XDebug connects to proxy server using xdebug.remote_host and xdebug.remote_port values. It sends an init packet with idekey and waits without executing any code.
  6. Proxy server looks up the idekey and finds the IDE address. It then sends the same init command to the IDE
  7. IDE negotiates features or set any breakpoints with the proxy server and proxy server sends the same commands to the XDebug
  8. IDE send commands to proxy server to interactively walk through the code. Proxy server proxies all commands and response to XDebug
  9. When finished, XDebug sends response back to browser.

Just-in-time Debugging (JIT)

  1. IDE/Editor starts a debug client server on PORT 9000
  2. XDebug starts code execution and stops when an error occurs
  3. XDebug connects to remote IDE using xdebug.remote_host and xdebug.remote_port values. It sends an init packet with idekey
  4. IDE negotiates features or set any breakpoints
  5. IDE send commands to interactively walk through the code
  6. When finished, XDebug sends response back to browser.