XDebug

A PHP extension that allows you to:

1. walk through your code by Remote Debugging
2. find bottlenecks in your application by Profiling
3. find Code Coverage in a single request
4. trace your application by logging all function calls

Remote Debugging

• Debug from host when server is running docker/vagrant
• Either debug on each request or JIT (Just-in-time) when error occurs
• Evaluate code/Modify variables at Run-time
• Debug web applications as well as CLI scripts
• Multi-user debugging with DBGp proxy

1. DBGp Prototocol:

Protocol Specification: https://xdebug.org/docs-dbgp.php

The protocol provides a means of communication between a debugger engine (XDebug) and a debugger IDE (IDE, etc.).

2. How it works

1. IDE/Editor starts a debug client server on PORT 9000
2. User sends session initiation command to the Debugger Engine (XDebug)
3. Debugger Engine(XDebug) initiates a debugging session and makes a connection to the remote IDE, send an INIT packet and wait. It doesn't execute any code yet
4. IDE negotiates features or set any breakpoints
5. IDE send commands to interactively walk through the code

Unknown IP/Multiple User:

Find out more of these charts here

3. Installing

Using PECL

pecl install xdebug

Next, update php.ini /usr/local/etc/php/php.ini with following directives:

zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20131226/xdebug.so

; Enable Remote Debugging
xdebug.remote_enable=1

; If enabled, ALWAYS start a Remote Debugging session,
; even if the GET/POST/COOKIE variable was not present
xdebug.remote_autostart=0

; Selects the host where the debug client is running
xdebug.remote_host=192.168.10.2

; The port to which Xdebug tries to connect on the remote host. 
xdebug.remote_port=9000

; If enabled, the xdebug.remote_host setting is ignored and 
; Xdebug will try to connect to the client that made the HTTP request. 
; It checks the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out remote IP
xdebug.remote_connect_back=1


; Selects when a debug connection is initiated.
; Available values: req, jit
xdebug.remote_mode=req

; Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. 
xdebug.idekey=PHPSTORM

4. Debugging Web applications

4.1 Signal Xdebug to Start a Session

• Using GET/POST parameters:
  • UseXDEBUG_SESSION_START=idekey in the GET/POST parameter to start a session. It'll also create a XDEBUG_SESSION cookie. Pass empty session name if you don't want to create any cookie.
  • Use XDEBUG_SESSION_STOP in GET/POST parameter to stop a session.
  • XDEBUG_SESSION_STOP_NO_EXEC: works in the same way as XDEBUG_SESSION_STOP, except that the script will not be executed
• Using HTTP Cookies:
  • Create a cookie XDEBUG_SESSION with any value to signal XDebug to start a debugging session
  • As long as the cookie is valid, you don't need to send another session start signal.
  • Default cookie lifetime is 1 hour.

4.2 xdebug.remote_connect_back:

If enabled, the xdebug.remote_host setting is ignored and Xdebug will try to connect to the client that made the HTTP request. It checks the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out which IP address to use.

Please note that there is no filter available, and anybody who can connect to the webserver will then be able to start a debugging session.

4.3 xdebug.remote_mode

Selects when a debug connection is initiated. This setting can have two different values:

• req (default): Xdebug will try to connect to the debug client as soon as the script starts.
• jit: Just-In-Time debug mode where Xdebug will only try to connect to the debug client as soon as an error condition or a breakpoint occurs.

5. Debugging CLI scripts

• remote_connect_back setting won't work
• There in no GET/POST/COOKIE paramater
• Use XDEBUG_CONFIG environment variable to start session

XDEBUG_CONFIG="remote_host=192.168.10.15 idekey=somekey" php /path/to/script.php

6. Debugging When PHP Server and IDE have no direct connection

Often it is the situation when the php server is running on a different network than your local network and there is a firewall which prevents communication between them. Or sometimes your local network isn't directly accessible from the internet. Couple of solution in that scenario are:

6.1 Reverse port-forwarding via SSH Tunneling

With ssh we can allocate a socket to listen to on the remote server and forward all requests to our local port over a secure tunnel:

ssh -N -T -R 9000:localhost:9000 user@host

and the php.in config on remote server would look like this:

xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_connect_back=0

6.2 Tunneling from a public endpoint via ngrok

Using ngrok we can make our Xdebug client publicly available so the remote server can connect to it. If your server is running on Kubernetes pods then this might be the easiest solution, since Kubernetes doesn't support reverse port-forwarding yet.

ngrok tcp 9000

Running above will give us a public endpoint, we can update our php.ini with that endpoint url:

xdebug.remote_host=0.tcp.ngrok.io
xdebug.remote_port=16751
xdebug.remote_connect_back=0

Find out more about debugging with ngrok at here

7. Available Clients:

• Debugclient : For CLI debugging
• Xdebug Chrome Addon
• IDE based clients:
  • SublimeText package: XDebug Client

8. Tips

• xdebug_break(): Add breakpoint in the code, like debugger command in javascript.
• Xdebug-helper: Chrome addon to start/stop remote debugging session. Uses cookies to start session.

9. Troubleshooting

10. Resources

• How extensions work: Zend API: Hacking the Core of PHP
• Remote Debugging Documentation
• MSGEN