xDebug
Introduction
Software development can be a difficult process, full of logic flows, data structures and concepts. Programs such as Moodle are developed by more than one person with their own understanding of the features they’re involved with. As a developer you want to understand how their code works such that you can then ensure that your functionality can interoperate with theirs or improve on what they have achieved, potentially fixing a flaw, a bug. You’re also human and prone to errors, you make mistakes and create flaws, again a ‘bug’ or ‘bugs’. Bugs are detected through testing. The process of bug removal is called ‘debugging’. This can be achieved in many ways: code inspection, additional debugging code that provides additional information that helps to understand what is going on, and the use of a ‘debugger’, an interactive tool that assists the debugging process. As Moodle’s ‘Controller’ element of the ‘Model View Controller’ design pattern (developer.mozilla.org/en-US/docs/Glossary/MVC) is written in PHP, the for interactive debugging we can use the ‘xDebug’ tool (xdebug.org). In this post I’ll describe how you can set it up for yourself.
Disclaimers
Names / logos can be trademarks of their respective owners. Please review their website for details. I am independent from the organisations mentioned and am in no way writing for or endorsed by them. The information presented in this article is written according to my own understanding, there could be technical inaccuracies, so please do undertake your own research. The featured image is my copyright, please don’t use without my permission.
A little background
I’ve known about xDebug for a while, indeed many years but always considered it too difficult to set up. That is until I came across this post ‘VSCode, Xdebug, and Remote Debugging: Need Help to Set Up’ (moodle.org/mod/forum/discuss.php?d=442461) and realised that it was perhaps easier than I thought and I could move away from the other methods I’d been using, or rather that using xDebug would be another tool I could use.
I also thought, now incorrectly, that xDebug was command line controlled, which I find tedious and slow. I want to concentrate on the issue in hand rather than putting too much effort into using the tool in the first place. Enter the IDE (Integrated Development Environment).
Using GUI interaction with an IDE
xDebug itself provides many features, but the one we’re interested in is the ‘Step debugger’ (xdebug.org/docs/step_debug) as it will allow us to step though the code line by line, determine the flow from the decisions being made and inspect the contents of the data structures. The IDE I have chosen is VSCode (code.visualstudio.com) as I’m already running it on my Windows development environment and it is also available for Linux, where I’m using Ubuntu for the purpose of this post.
Starting point
I assume that you already have Moodle installed and working, and that you’ve installed VSCode. Then opened your Moodle folder and saved as a ‘Workspace’:
Installing
First install xDebug with ‘sudo apt install php8.2-xdebug’. I’m using PHP 8.2, so if yours is different, then adjust accordingly. If you are using windows, then you can get the xDebug extension from xdebug.org/download/historical, which will be a ‘dll’ that you can download and add as an extension in the php.ini file (‘zend_extension=xdebug’ – filename renamed).
Next we need to configure it to use ‘step debugging’ and to activate with a request (saves having to install a browser plugin), so edit the ‘xdebug.ini’ file, ‘sudo nano /etc/php/8.2/mods-available/xdebug.ini’, which will already have ‘zend_extension=xdebug.so’ and add:
xdebug.mode=debug, develop xdebug.start_with_request=yes
More information on xdebug.org/docs/step_debug and https://xdebug.org/docs/develop.
Then we need to turn off ‘output_buffering’ as it’s recommended here moodle.org/mod/forum/discuss.php?d=442461#p1779687 – in the PHP ini file, ‘sudo nano /etc/php/8.2/apache2/php.ini’:
Next restart Apache with ‘sudo systemctl restart apache2’ and then look at the PHP information in Moodle (Site administration → Server → PHP info):
Where you can see the features we’ve enabled, along with a ‘Docs’ link on the right hand side.
Next install the VSCode xDebug extension (marketplace.visualstudio.com/items?itemName=xdebug.php-debug):
And finally, we need a ‘launch configuration’ to tell VSCode’s debugging interface what to do. On the ‘Run and debug’ activity, click on ‘create a launch.json file’:
Then select ‘workspace’:
So that VSCode saves it there rather than in the Moodle install folder, where its possible the permissions won’t allow it. Then select the PHP debugger:
Which will then create the default values for you:
I’ve had to change the ‘path’ to use an absolute path reference rather than a relative one. With that saved then we’re all set to start debugging. We will be using the ‘Listen for xDebug’ configuration, so if you wish to remove the others from the JSON then do.
Debugging
On the ‘Explorer’ activity, open the file of interest and then go to the ‘Run and debug’ activity, where you can set a breakpoint:
Then run the ‘Listen for xDebug’ configuration:
With the green right pointing triangle icon. Then when running, we refresh out Moodle page (here in Firefox):
And all being well, the debugger will pause and we can inspect the variables, such as ‘$hassiteconfig’ been set to ‘true’ on line 62. And that’s it!
You can find more information on code.visualstudio.com/docs/editor/debugging and marketplace.visualstudio.com/items?itemName=xdebug.php-debug about how to debug and configure xDebug.
Conclusion
I hope this helps you to get interactive step debugging up and running.
- Settings transfer – 16th October 2024
- Added value – 16th September 2024
- What is a developer? – 16th August 2024
