Moodle PHP debugging in VS Code

While developing a tool which communicates with Moodle via the LTI API, I’ve stumbled upon countless exceptions inside the Moodle source code. Often I would simply get a page that displays a generic message like:

Moodle exception during a request

Unfortunately, even though with debug messages in Moodle being enabled, printed exceptions are not fully shown or do not give any hint on what is actually going on in the code. I often can not identify whether the problem is on my side or originates in one of the countless bugs in Moodle. In order to develop a new plugin or a tool connected to the learning management system (LMS), debugging is inevitable. The Moodle docs themselves provide a starting point for displaying error messages and enabling code specific settings. However, there is no advice on how to actually get the debugger running. So, after countless hours, I managed to debug the Moodle source code in VS Code and I am going to show you how. So let's get started 🚀

Installation

What we need for this guide:
- VS Code
- PHP installation (when not using the Moodle installer)
- Docker (optionally)
- Moodle installation
- VS Code PHP extension

Moodle can be either launched in a Docker container, offering flexibility for Linux users, as well as a secure environment. Or it can be launched as a standalone installation. For Windows users there is a prepackaged download available, including both the Moodle files and the server necessary to run it.
The downside of using Docker is when it comes to networking and requests. The advantage is the easy update and maintenance. I would recommend using the standalone installation, as it offers more control.

If you do not have your VS Code running, go ahead and download it from here. You also need the VS Code PHP Extension.
Next download a recent version of PHP if you do not follow the Moodle installer and want to run Moodle yourself using a custom webserver. Extract it somewhere and add the “php” folder to your Path environment variable. This is required by the extension.
Next, either choose the Standalone chapter or the Docker chapter.

Since I am using a Windows machine, the following will be Windows specific, but with a little adaptation you can get it running on Linux or Mac OS. First, download an extract the installer. Inside the folder, first launch “Start Moodle.exe”. This sometimes does not work ( as so often with Moodle🙄). So simply go inside the “server” folder and launch “xampp-control.exe”. Here, fire up “MySQL” and after it “Apache”.
You should be able to navigate to “http://localhost” by now. Follow the install instructions in your browser. When you are done, gracefully shutdown both apache and mysql in the xampp control panel. Now, add the “php” folder in your “server” folder to your Path environment variable. This is required by the VS Code PHP extension.

Install Docker. Then copy following “docker-compose.yml” to a location of your choice:

version: '2'
services:
mariadb:
image: docker.io/bitnami/mariadb:10.6
ports:
- '3306:3306'
environment:
# ALLOW_EMPTY_PASSWORD is recommended only for development.
- ALLOW_EMPTY_PASSWORD=yes
- MARIADB_USER=bn_moodle
- MARIADB_DATABASE=bitnami_moodle
- MARIADB_CHARACTER_SET=utf8mb4
- MARIADB_COLLATE=utf8mb4_unicode_ci
volumes:
- 'mariadb_data:/bitnami/mariadb'
moodle:
image: docker.io/bitnami/moodle:4
ports:
- '80:8080'
- '443:8443'
environment:
- MOODLE_DATABASE_HOST=mariadb
- MOODLE_DATABASE_PORT_NUMBER=3306
- MOODLE_DATABASE_USER=bn_moodle
- MOODLE_DATABASE_NAME=bitnami_moodle
# ALLOW_EMPTY_PASSWORD is recommended only for development.
- ALLOW_EMPTY_PASSWORD=yes
volumes:
- 'moodle_data:/bitnami/moodle'
- 'moodledata_data:/bitnami/moodledata'
depends_on:
- mariadb
volumes:
mariadb_data:
driver: local
moodle_data:
driver: local
moodledata_data:
driver: local

Now start a terminal in the folder containing the file and run:
$ docker-compose up -d

In Docker, first run the mariadb image, then start the docker_moodle image. The first launch might take a couple of minutes. Standard username and password for Moodle are user and bitnami. Remember to change them after your first login.
In VS Code install the Docker extension. Now connect to the running container like so:

Connecting to a running docker instance
attach VS Code
  1. Select the docker extension
  2. Rightclick on the Moodle container running
  3. Press “Attach Visual Studio Code”

In the new window we launch a terminal in VS Code and enter apt update followed by apt install php-xdebug . You are ready to configure Xdebug.

Configure Xdebug

Navigate to your php folder inside the “server” folder or the “bitnami” folder when you use Docker. Now launch a terminal and start php.exe -iin Windows or php -ifor Linux. Copy the output and put it into the Xdebug install wizard. This will most likly tell you that you do not have Xdebug installed yet, if you do not use Docker. So follow the instructions in the wizard to download and activate the php extension, if not already done. The wizard prompts you to add the line “zend_extension=xdebug” to your php.ini. Below this line, we add some settings that allow us to hook into the debugging session:

[XDebug]
xdebug.output_dir = tmp
xdebug.start_with_request=yes
xdebug.mode=develop,debug
xdebug.client_port=9000
xdebug.remote_handler=dbgp
xdebug.discover_client_host=1
; xdebug.client_host=host.docker.internal
xdebug.start_with_request=1
xdebug.idekey=VSCODE
xdebug.max_nesting_level=1500

When using Docker, uncomment the according line. This config tells us where to output logs, on what port we are listening to debug calls and how our IDE is identified.

In VS Code we now add a launch configuration that should look somewhat like this:

{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9000
}
]
}

Here we specified that we want VS Code to listen to port 9000, as configured in the “php.ini”. According to the Moodle docs, we can add following lines at the end into “config.php” at the root of the Moodle installation:

@ini_set('display_errors', '1'); // NOT FOR PRODUCTION SERVERS!
$CFG->debug = 32767; // DEBUG_DEVELOPER // NOT FOR PRODUCTION SERVERS!
// for Moodle 2.0 - 2.2, use: $CFG->debug = 38911;
$CFG->debugdisplay = true; // NOT FOR PRODUCTION SERVERS!

// You can specify a comma separated list of user ids that that always see
// debug messages, this overrides the debug flag in $CFG->debug and $CFG->debugdisplay
// for these users only.
$CFG->debugusers = '2';

Remember to remove the lines when going into production.
To finish it off, we launch our webserver again and navigate to “http://localhost/admin/phpinfo.php”. When searching for “xdebug” you should see something like this:

Xdebug information in the moodle php admin interface

Launching your configuration in VS Code by pressing F5 should attach your instance to the running Moodle debug session. If this fails, first launch the Debugger in VS Code and then start your Moodle Webserver.

Congrats🎉!
Your breakpoints 🔴should work as intended.
(Small advise: To avoid the constant breakpoints in one of Moodle’s countless exceptions, remove the two ticks at:

in your debug menu.)

Additions

Developing some features of Moodle requires OpenSSL to be enabled. You can uncomment the line in your php.ini file: extension=openssl . Afterwards navigate to “server\apache” and launch “makecert.bat” when on windows. A guide will lead you trough the generation of the certificates.

Under “Site administration” go to “Development” and in “Debugging” enable “Debug messages”. This outputs less opaque errors in the UI.

References

Moodle docs: https://docs.moodle.org/401/en/MoodleDocs:Overview visited on 17.01.2023
Xdebug: https://xdebug.org/ visited on 17.01.2023
Docker: https://www.docker.com/products/docker-desktop/ visited on 17.01.2023
VS Code Marketplace: https://marketplace.visualstudio.com/vscode visited on 17.01.2023
PHP: https://www.php.net/ visited on 17.01.2023
Moodle Bug tracker: https://tracker.moodle.org/browse/MOBILE-4232?jql= visited on 17.01.2023

--

--

M. Sc. in Computer Science, currently working in ed project as frontend lead and researcher in ML/DL

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
David Fischer

M. Sc. in Computer Science, currently working in ed project as frontend lead and researcher in ML/DL