Debugging

For now, this subject will focus on PHP.

Debugging a PHP application can involve quite a bit of machinery, and effort getting that machinery setup. But it's worth it because what alternative is there? echo? Come on!

Thanks to Derick Rethans, XDebug can do a ton of cool things for you. For example, it overloads var_dump() and gives you control over how you want deeply nested data structures to be displayed.

XDebug[edit]

XDebug is a tool you can't live without once you've learned how to use it.

It offers:

Step Debugging
Improvements to PHP's error reporting
Tracing
Profiling
Code Coverage Analysis

XDebug 3.2.0 was released in Dec. 2022 and adds support for PHP 8.2 and drops support for PHP 7.2-7.4

More recent releases of XDebug are 3.3.2 and all the way up to 3.4.1 as of Jan 2025

Installing XDebug[edit]

Installing XDebug is fairly complicated and only gets more challenging if you are trying to debug sources inside a container or on a remote server. And since the PHP cli is different from the web interpreter, there are differences depending on how you are invoking PHP

https://xdebug.org/docs/install

Install[edit]

Ensure that XDebug PHP extension is installed for your PHP environment. It is typically installed via PECL, but can be installed with package managers.

in the console, you can just type php -v which will tell you not just the version of PHP, but also whether XDebug is enabled. More specifically, you could php -r 'echo phpversion("xdebug");'

You should also check the settings of your installation by looking at the ini file for XDebug
php --ini shows you the ini files that are loaded for your PHP. Inspect the one related to XDebug and ensure that it is set for Debugging.

cat /etc/php/8.3/cli/conf.d/99-xdebug.ini

zend_extension=xdebug
xdebug.mode=coverage,develop,debug,profile,trace

Beware that although the mode is critical and can only be set in the ini file, that setting can be overridden by the environment variable XDEBUG_MODE - so look for that in container-driven setups.

Configuration Report[edit]

Create a file like info.php on your development host, and then browse it for a full report of your Debugging environment.

# choose a target
myFile='../../info.php';
# add the phpinfo() function
echo -e "<?php \nphpinfo();\n" > $myFile;
# add the xdeub_info() function
echo -e "\n\nxdebug_info();\n" >> $myFile;

XDebug with VSCode[edit]

VSCode only supports debugging JavaScript out of the box (including Node.js and TypeScript). For PHP and other languages from Go to Python, you will need to install a debugger extension in VSCode. XDebug is the debugger for PHP, and you will need the PHP Debug extension to VSCode. READ the documentation on that page thoroughly. The extension integrates your IDE with the PHP environment and the XDebug debugger itself.

Step Debugging[edit]

Covered at https://xdebug.org/docs/step_debug

Deeper Dive[edit]

We did an old deep dive using NetBeans and XDebug on a complex CiviCRM mailer embedded as a module in Drupal

A more current setup would be Debug Semantic MediaWiki in Docker using VSCode and XDebug.