Skip to content

Moodle Architecture, Plugins and APIs

Moodle LMS is a PHP application built as a small core surrounded by plugins. Almost everything a teacher or student sees, from the Quiz activity to the login method to the theme, is a plugin that the core loads through well-defined APIs. Understanding that split explains how to extend Moodle safely, how to upgrade it, and how other systems talk to it. The running example is an invented training site, Northwind Academy, at learn.example.test, which syncs staff from an HR system and sells courses through a separate shop.

Facts on this page are checked against the Moodle LMS 5.3 release notes and source (5.3 is the long-term support release published in October 2026; security fixes run to October 2029). Where behavior changed in a recent version, the section says which.

Topic What it answers
Layers What runs where: web server, PHP code, database, data directory, cron and caches
Database layer Supported databases and the DML API
Plugin system Plugin types, naming, folder layout and installation
Themes and front end Boost, templates and JavaScript
Web services REST and SOAP endpoints, tokens and a sample call
LTI Embedding external tools and publishing Moodle content to other platforms
Authentication and single sign-on Login methods in core and common SSO setups
Integration patterns HR sync, e-commerce enrolment and reporting

A Moodle site has five moving parts:

  • Web server and PHP. Apache or nginx runs Moodle’s PHP code. Moodle 5.3 needs PHP 8.3 or later (8.4 is supported), 64-bit only, with the sodium extension and max_input_vars of at least 5000.
  • Code directory. Since Moodle 5.1 the web-accessible code lives in a public subdirectory, and the web server’s document root must point there (DocumentRoot /srv/moodle/public instead of /srv/moodle). Command-line scripts such as admin/cli/upgrade.php and config.php stay at the top level, outside the web root.
  • Database. Courses, users, enrolments, grades, logs and configuration live in a relational database (next section).
  • Data directory (moodledata). Uploaded files, caches, sessions and temporary files are stored outside the code directory. Files are stored once by content hash and referenced from the database, so two teachers uploading the same PDF use one copy on disk.
  • Cron and caches. Scheduled and ad hoc tasks (sending forum digests, running backups, processing completions) run from admin/cli/cron.php, typically every minute. The Moodle Universal Cache (MUC) caches configuration and data in files by default, and can use Redis or other stores on busy sites.

Pitfalls:

  • Document root left at the old path after upgrading to 5.1 or later. The site breaks or, worse, exposes non-public files. Update the Apache or nginx root as part of the upgrade.
  • Cron not running. Many features look broken (no notifications, completions never update) when the only problem is a missing cron job.

Moodle 5.3 supports PostgreSQL 17 or later, MySQL 8.4 or later, MariaDB 11.4 or later, Aurora MySQL and Microsoft SQL Server 2019 or later. Oracle Database support was removed in Moodle 5.0. Plugins never write SQL for a specific engine; they use the Data Manipulation API through the global $DB object (get_record, get_records_sql, insert_record, update_record) and describe their tables in an XMLDB file (db/install.xml) so the same plugin works on every supported database. Schema changes between plugin versions go in db/upgrade.php.

<?php
// Fragment from a local plugin: count active enrolments in a course with the DML API.
// Not run here (needs a Moodle site); placeholders are named and typed, never concatenated.
$sql = "SELECT COUNT(1)
FROM {user_enrolments} ue
JOIN {enrol} e ON e.id = ue.enrolid
WHERE e.courseid = :courseid AND ue.status = :active";
$count = $DB->count_records_sql($sql, ['courseid' => $courseid, 'active' => ENROL_USER_ACTIVE]);

Table names in braces are expanded with the site’s table prefix (usually mdl_), which is why plugins must not hard-code mdl_user.

Plugins are Moodle’s main strength: the official directory lists thousands of community plugins, and the core itself is largely made of plugins. Each plugin type has a fixed folder and a component prefix (Moodle calls the naming scheme “Frankenstyle”), for example mod_quiz lives in public/mod/quiz and auth_oauth2 in public/auth/oauth2.

Plugin type Component prefix Folder (under public/) Examples
Activity modules mod mod Quiz, Assignment, Forum, H5P, BigBlueButton
Blocks block blocks Timeline, Calendar, Recently accessed courses
Themes theme theme Boost
Authentication auth auth Manual accounts, Email-based self-registration, LDAP, OAuth 2
Enrolment enrol enrol Manual, Self enrolment, Enrolment on payment, Publish as LTI tool
Question types qtype question/type Multiple choice, Drag and drop into text
Reports report report Logs, Activity completion
Admin tools tool admin/tool Upload users, Multi-factor authentication
Local plugins local local Site-specific customizations with no better home
Web service protocols webservice webservice REST, SOAP

Every plugin has a version.php that declares its component name, version number and the minimum Moodle version it requires. When an administrator visits the notifications page (or runs php admin/cli/upgrade.php), Moodle compares those versions with the database and runs the install or upgrade steps.

Installing a plugin on a self-hosted site: download a version that lists your Moodle release as supported from the Moodle plugins directory, then either install it from Site administration > Plugins > Install plugins, or extract it into the matching folder (for example public/mod/ for an activity) and run the upgrade. For repeatable deployments, add plugins to your code repository or build pipeline rather than uploading through the browser on production. MoodleCloud plans restrict which plugins you can add.

Pitfalls:

  • Installing a plugin built for an older release. Check the “Supported Moodle versions” on the plugin page; many plugins needed changes for the public folder in 5.1.
  • Editing core files instead of writing a plugin. Core edits are lost or conflict at every upgrade. A local plugin, a theme override or a hook callback almost always does the job.
  • Too many plugins. Each third-party plugin is code you must keep compatible and secure through every upgrade. Prefer core features where they are close enough.

The default theme is Boost, built on Bootstrap; the older Classic theme was removed from core in Moodle 5.3, so sites still on Classic must move to Boost or a Boost-based child theme before upgrading. Themes override Mustache templates and SCSS rather than PHP logic, which keeps them upgrade-friendly. Front-end behavior is written as JavaScript modules, and Moodle 5.3 adds a standard way to mount React components alongside the existing templates. The official Moodle App (iOS and Android) does not use the web theme at all; it talks to the site through web services, so mobile access requires the mobile web service to be enabled.

Moodle’s External Services API exposes functions such as core_webservice_get_site_info, core_user_get_users_by_field, core_course_get_courses_by_field and enrol_manual_enrol_users. The same functions power AJAX calls in the web interface and the Moodle App. Moodle 5.3 ships two protocols in core, REST (/webservice/rest/server.php, with JSON responses when you pass moodlewsrestformat=json) and SOAP; XML-RPC and AMF, mentioned in older guides, are no longer in core.

To let an external system call Moodle, an administrator enables web services and the protocol, creates a dedicated user with only the capabilities it needs, creates an external service containing only the required functions, and issues a token for that user and service. A client can also request a token from /login/token.php, which only accepts POST requests for credentials.

# sync_check.py — fragment: not run here (needs a Moodle site and a token).
# Calls core_webservice_get_site_info, then looks up a user by email.
import os
import requests
MOODLE = "https://learn.example.test"
TOKEN = os.environ["MOODLE_WS_TOKEN"] # never hard-code tokens
def call(function: str, **params) -> dict | list:
response = requests.post(
f"{MOODLE}/webservice/rest/server.php",
data={"wstoken": TOKEN, "wsfunction": function, "moodlewsrestformat": "json", **params},
timeout=15,
)
response.raise_for_status()
body = response.json()
if isinstance(body, dict) and "exception" in body: # Moodle reports errors with HTTP 200
raise RuntimeError(f"{body['errorcode']}: {body['message']}")
return body
site = call("core_webservice_get_site_info")
print(site["sitename"], site["release"])
users = call("core_user_get_users_by_field", field="email", **{"values[0]": "dana@example.test"})
print([u["id"] for u in users])

Array parameters are flattened as values[0], values[1] in form-encoded requests. Each site documents its enabled functions and parameters under Site administration > Server > Web services > API Documentation.

Pitfalls:

  • Checking only the HTTP status. Moodle returns HTTP 200 with an exception object when a call fails, so clients must inspect the body.
  • One all-powerful token. Give each integration its own user, service and token with the smallest set of functions, so a leaked token cannot change grades or site settings.

Learning Tools Interoperability (LTI) is the 1EdTech standard for connecting a learning platform to external tools with single sign-on and grade return. Moodle supports it in both directions. As a platform, the External tool activity lets a teacher embed a third-party simulation, coding exercise or video tool in a course; with LTI 1.3 and LTI Advantage the tool can create gradebook columns, send grades back and read the course roster. As a tool, the “Publish as LTI tool” enrolment method lets Northwind Academy offer one of its Moodle courses inside another institution’s platform, with learners enrolled automatically on first launch. Prefer LTI 1.3 for new connections; it replaces the shared-secret signing of LTI 1.0 and 1.1 with signed JSON Web Tokens and registered keys.

Core authentication plugins in Moodle 5.3 include manual accounts, email-based self-registration, LDAP, OAuth 2, Shibboleth and LTI (for users who arrive through an LTI launch). OAuth 2 services for Google, Microsoft and Facebook have presets, and any OpenID Connect provider can be configured as a custom service, which covers most “log in with Microsoft 365 or Google Workspace” requirements. SAML 2.0 is provided by widely used community plugins rather than core. Moodle 5.3 also has a core multi-factor authentication tool (tool_mfa). Only enable the methods you use and disable self-registration on sites that should not accept public sign-ups.

  • HR system to Moodle. Northwind Academy’s nightly job reads new and changed staff from the HR system and calls core_user_create_users, core_user_update_users and enrol_manual_enrol_users through a dedicated web service user. For a one-off load, the Upload users admin tool accepts a CSV file. With SSO, users are matched on a stable identifier (an employee ID in the idnumber field), never on display name.
  • Selling courses. Core includes an “Enrolment on payment” method with payment gateway plugins (PayPal ships in core). When the shop is a separate system, its order webhook calls a small service that enrols the learner through the web services API.
  • Reporting. Course completion and grade data can be read through web services (core_completion_get_course_completion_status), exported from the report builder as CSV or Excel, or copied to a data warehouse from a read replica of the database, which keeps heavy analytics queries away from the live site.
Need Use Avoid
Change how Moodle looks A Boost child theme Editing core templates in place
Add behavior inside Moodle A plugin of the right type (local as a last resort) Core patches
Read or change Moodle data from another system Web services with a scoped token Writing directly to the database
Show an external tool inside a course LTI 1.3 External tool Iframes with shared passwords
Let users log in with company accounts OAuth 2 or OpenID Connect, LDAP, or a SAML plugin Syncing passwords

1. Why does Moodle 5.1 and later serve code from a public folder? To separate web-accessible files from code and configuration that should never be served over HTTP. Only public is the document root; CLI scripts and config.php stay outside it. It requires a one-time web server change during the upgrade.

2. A plugin needs a new table. How do you add it so it works on PostgreSQL and SQL Server? Define the table in the plugin’s db/install.xml with the XMLDB editor, add the creation step for existing sites in db/upgrade.php, bump the version in version.php, and access it only through the $DB API with named placeholders. Moodle generates engine-specific SQL.

3. An integration’s calls “succeed” but nothing changes in Moodle. What do you check first? The response body: Moodle returns HTTP 200 with an exception, errorcode and message when a web service call fails, often because the function is not in the service, or the service user lacks a capability in that context.

4. When would you choose LTI over web services? LTI is for user-facing launches: a learner clicks into an external tool with single sign-on and the grade flows back. Web services are for system-to-system data exchange without a user in the loop, such as nightly enrolment sync.

5. Senior scenario: Northwind Academy runs Moodle 4.5 with 25 third-party plugins and the Classic theme. How do you plan the move to 5.3? Inventory plugins and check each for 5.3 support, replacing abandoned ones with core features where possible. Move to Boost or a Boost child theme first, since Classic is gone in 5.3. Confirm server prerequisites (PHP 8.3, PostgreSQL 17 or the matching MySQL or MariaDB version) and plan the public document root change. Rehearse the upgrade on a copy of production data with admin/cli/upgrade.php, run integration tests against the web services the HR sync uses, and schedule the cut-over with a tested rollback (database and moodledata backups).