Debugging: Difference between revisions

Latest revision as of 15:51, 13 February 2025

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.

@@ Line 1: / Line 1: @@
-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? <code>echo</code>?  Come on!
+For now, this subject will focus on PHP.
-Thanks to [http://derickrethans.nl/who.html Derick Rethans], xdebug can do a ton of cool things for you.  For example, it overloads <code>[https://secure.php.net/var_dump var_dump()]</code> and gives '''you''' [http://www.xdebug.org/docs/display control over how you want deeply nested data structures to be displayed].
+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? <code>echo</code>?  Come on!
-== First get Xdebug setup ==
+Thanks to [http://derickrethans.nl/who.html Derick Rethans], XDebug can do a ton of cool things for you.  For example, it overloads <code>[https://secure.php.net/var_dump var_dump()]</code> and gives '''you''' [http://www.xdebug.org/docs/display control over how you want deeply nested data structures to be displayed].
-Xdebug is the project for debugging PHP.  The [http://xdebug.org/wizard.php wizard] will show you how to upgrade your package version.  In my case, the Xdebug packaged for Ubuntu was 2.2.3, but the more recent version is '''2.3.3'''
-=== Summary ===
+== XDebug ==
-Here is what the wizard reported for me AFTER my recent installation of xdebug
+XDebug is a tool you can't live without once you've learned how to use it.
-<blockquote>
-'''Xdebug installed:''' 2.3.3 <br />
-'''Server API:''' Apache 2.0 Handler <br />
-'''Windows:''' no <br />
-'''Zend Server:''' no <br />
-'''PHP Version:''' 5.5.9-1 <br />
-'''Zend API nr:''' 220121212 <br />
-'''PHP API nr:''' 20121212 <br />
-'''Debug Build:''' no <br />
-'''Thread Safe Build:''' no <br />
-'''Configuration File Path:''' /etc/php5/apache2 <br />
-'''Configuration File:''' /etc/php5/apache2/php.ini <br />
-'''Extensions directory:''' /usr/lib/php5/20121212+lfs
-</blockquote>
-Caveat: their script can't really tell where the xdebug configuration lives.  In Ubuntu, there might be a file in <code>/etc/php5/conf.d</code> In my case I actually did have <code>/etc/php5/conf.d/xdebug.ini</code>, but that file is superfluous because there are symbolic links for both '''apache2''' and '''cli''' that go to
-<code>/etc/php5/mods-available/xdebug.ini</code> (which helps PHP configuration to be the same for both runtimes.)  Bottom line: run <code>locate xdebug.ini</code> to find out whether you have a duplicate/conflicting file; merge those files down to one; and make any overrides that you need from the default settings which xdebug will use if left unconfigured.  Then <code>sudo service apache2 restart</code> and check your phpinfo() for correctness.
-The defaults are probably all good, but you many want to specify some of the following:
+It offers:
-<source lang="ini">
-;zend_extension=/usr/lib/php5/20090626+lfs/xdebug.sozend_extension=/usr/lib/php5/20121212+lfs/xdebug.so
-; enable debugging
+*   Step Debugging
-xdebug.remote_enable = On
+*   Improvements to PHP's error reporting
-; working from local machine
+*   Tracing
-; xdebug.remote_host = "127.0.0.1"
+*   Profiling
-; debugging from any machine on the local network, as well as through the router
+*   Code Coverage Analysis
-xdebug.remote_host = "192.168.1.0/24,127.0.0.1"
-; set which debug client protocol we want
-xdebug.remote_handler = "dbgp"
-</source>
+XDebug 3.2.0 was [https://xdebug.org/announcements/2022-12-08 released in Dec. 2022] and adds support for '''PHP 8.2''' and drops support for PHP 7.2-7.4
-Once you see xdebug in your phpinfo() output, you know it's enabled -- which means that you can already get xdebug functionality out of your PHP scripts (e.g. var_dump() is overridden).  But how do you get debugging working so that you can use it with your IDE?  That is covered in the '[http://www.xdebug.org/docs/remote remote]' section of the manual.
+More [https://xdebug.org/announcements recent releases of XDebug] are 3.3.2 and all the way up to '''3.4.1''' as of Jan 2025
-Following the sage advice of the [http://wiki.netbeans.org/HowToConfigureXDebug#General_Information Netbeans wiki], you want to get xdebug's '''debugclient''' working on localhost first, then add Netbeans.
+=== Installing XDebug ===
+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
-xdebug provides several configuration parameters as well as functions that you can use in your debugging code.  One important parameter is the <code>[http://www.xdebug.org/docs/stack_trace xdebug.file_link_format]</code> which determines the format of the links that are shown in stack traces.  This allows for integration with your IDE so that, for example, Netbeans will find and open the file in your local sources.
+https://xdebug.org/docs/install
-[http://www.xdebug.org/docs/profiler Profiling] your PHP code is another feature enabled by xdebug.
+== Install ==
+Ensure that XDebug PHP extension is installed for your PHP environment. It is typically installed via [[PEAR|PECL]], but can be installed with [[Package management|package managers]].
+in the console, you can just type <code>php -v</code> which will tell you not just the version of PHP, but also whether XDebug is enabled. More specifically, you could <code>php -r 'echo phpversion("xdebug");'</code>
+You should '''also''' check the settings of your installation by looking at the <code>ini</code> file for XDebug<br>
+<code>php --ini</code> 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.
+<code>cat /etc/php/8.3/cli/conf.d/99-xdebug.ini</code>
+<syntaxhighlight lang="bash">
+zend_extension=xdebug
+xdebug.mode=coverage,develop,debug,profile,trace
+</syntaxhighlight>
+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 ===
+Create a file like '''info.php''' on your development host, and then browse it for a full report of your Debugging environment.
+<syntaxhighlight lang="bash">
+# 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;
+</syntaxhighlight>
+== XDebug with VSCode ==
+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 [https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug '''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 ==
+Covered at https://xdebug.org/docs/step_debug
+== Deeper Dive ==
+We did an old deep dive using NetBeans and XDebug [[CiviCRM/debugging|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]].
+[[Category:Debugging]]
+[[Category:Development]]