PHP Debugging

We use the PHP extension Xdebug for debugging purposes. In the following we describe the Xdebug Debug and Profile feature. For more features and details please refer to the Xdebug documentation.

Step Debugging

Xdebug’s step debugger allows you to interactively walk through your code to debug control flow and examine data structures. You can use any IDE that supports Xdebug (DBGp protocol). This also includes PhpStorm and Visual Studio Code (with the PHP Debug Extension).

To start you need to load Xdebug, enable the debug feature in ~/cnf/php.ini, and then reload PHP with php-reload.

zend_extension = xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 15750

Afterward, Xdebug sends debugging information to the defined address and port. Typically, your debugger does run within your local IDE. To allow the debugging connection to reach your local machine, use a reverse SSH port forwarding as follows:

ssh -R 127.0.0.1:15750:127.0.0.1:9003 <username>@<hostname>
     ▲             ▲              ▲         ▲
     │             │              │         │
     │       xdebug.client_port   │    Website name and Server
Reverse forward                Your IDE

Your local IDE now has access to the debugging connection at 127.0.0.1:9003.

Hint

To run multiple debug sessions for different websites concurrently, use different xdebug.client_port settings for each website.

Xdebug Profile

Xdebug’s built-in profiler allows you to find bottlenecks in your script and visualize those with an external tool such as KCacheGrind or QCacheGrind.

To start you need to load Xdebug, enable the profile feature in ~/cnf/php.ini, and then reload PHP with php-reload.

zend_extension = xdebug.so
xdebug.mode = profile
xdebug.start_with_request = yes

Afterward, Xdebug will save tracing files to the /tmp/ directory.

Trigger

Instead of processing all requests, Xdebug also does support running through a trigger. The trigger ensures that the feature is not activated for every but only for selected requests. To enable trigger mode, set xdebug.start_with_request in ~/cnf/php.ini to trigger instead of yes, and then reload PHP with php-reload.

xdebug.start_with_request = trigger

Afterward, add XDEBUG_TRIGGER as GET/POST parameter, or set a cookie namend XDEBUG_TRIGGER to notify Xdebug to process the current request.