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.
Topics on this page
Section titled “Topics on this page”| 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 |
Layers
Section titled “Layers”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
sodiumextension andmax_input_varsof at least 5000. - Code directory. Since Moodle 5.1 the web-accessible code lives in a
publicsubdirectory, and the web server’s document root must point there (DocumentRoot /srv/moodle/publicinstead of/srv/moodle). Command-line scripts such asadmin/cli/upgrade.phpandconfig.phpstay 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.
Database layer
Section titled “Database layer”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.
Plugin system
Section titled “Plugin system”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
publicfolder in 5.1. - Editing core files instead of writing a plugin. Core edits are lost or conflict at every upgrade. A
localplugin, 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.
Themes and front end
Section titled “Themes and front end”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.
Web services
Section titled “Web services”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 osimport 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
exceptionobject 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.
Authentication and single sign-on
Section titled “Authentication and single sign-on”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.
Integration patterns
Section titled “Integration patterns”- 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_usersandenrol_manual_enrol_usersthrough 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 theidnumberfield), 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.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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).
Related pages
Section titled “Related pages”- What is Moodle? — the section start page and reading order
- Getting started with Moodle — try Moodle hands-on
- Moodle vs WordPress — LMS versus CMS, and how they work together