Moodle db/services.php Reference for Plugin Developers

The Moodle services.php file, db/services.php in a plugin, is where Moodle learns which external functions the plugin provides and, optionally, which pre-built services bundle them. It holds two arrays: $functions, which maps each function name to its implementing class and options, and $services, which defines services an administrator can enable for an integration. Moodle copies part of it into the database when the plugin is installed or upgraded and reads the rest straight from the file on each call, and that split explains most "my change did nothing" problems.

This is a key-by-key reference with the default each key gets, where it is stored and what an upgrade does when you change or remove it. If you are writing your first function, start with our walkthrough on creating a Moodle web service function with core_external and come back here for the details. Checked against the Moodle 5.3.0 source (public/lib/upgradelib.php, public/lib/external/classes/external_api.php, public/lib/ajax/service.php, UPGRADING.md) and the Moodle developer documentation for the External API, October 2026.

File layout

<?php
// local/acmesync/db/services.php
defined('MOODLE_INTERNAL') || die();

$functions = [
    'local_acmesync_get_enrolments' => [
        'classname'    => 'local_acmesync\external\get_enrolments',
        'description'  => 'Returns enrolments changed since a timestamp.',
        'type'         => 'read',
        'ajax'         => false,
        'capabilities' => 'moodle/course:enrolreview',
    ],
];

$services = [
    'ACME sync' => [
        'functions'          => ['local_acmesync_get_enrolments'],
        'requiredcapability' => 'local/acmesync:use',
        'restrictedusers'    => 1,
        'enabled'            => 0,
        'shortname'          => 'local_acmesync',
    ],
];

Function names follow [frankenstyle_component]_[methodname], with the method usually a verb and a plural noun, such as get_enrolments. The implementing class lives in the plugin's external namespace, here local/acmesync/classes/external/get_enrolments.php, and extends \core_external\external_api (the namespaced API since Moodle 4.2, MDL-76583). The old global \external_api and related classes are deprecated in 5.3 (MDL-81225). Not run on a live site; test on staging first.

$functions keys

$services keys

A service is a named bundle of functions that tokens are issued against. Defining one is optional; without it, an administrator builds a custom service in the web UI. The array key is the service name, and Moodle matches existing services on that name plus your component.

What happens on install and upgrade

When a plugin is installed or its version changes, upgrade_component_updated() calls external_update_descriptions() for that component. It reads the file and syncs the tables:

• New functions get a row in external_functions; changed classname, methodname, classpath, capabilities or services values are updated.
• A function you delete from $functions loses its external_functions row. Its entries in custom services are kept on purpose so administrators can see the function has gone.
• A service you delete from $services is removed along with its function list, its authorised users and every token issued for it.
• After all plugins are upgraded, external_update_services() adds functions to the services named in their services key. It only adds to services defined in code (those with a component), never to services an administrator created.

The keys marked "read from the file" in the first table are read by external_function_info() when the function is called, so a change to ajax or loginrequired applies as soon as the file is deployed. Everything stored in the database needs a version bump in version.php; see our version.php reference. In 5.3 run the upgrade with php admin/cli/upgrade.php from the project root, since admin/cli sits outside public/.

Changes that break integrations

• Renaming a service key. Moodle sees the old name as removed and the new one as added, so existing tokens are deleted. Keep the key stable and change the description elsewhere.
• Renaming a function. Clients calling the old name fail. Add the new function, mark the old one deprecated with execute_is_deprecated() returning true and the @deprecated PHPDoc tag, and remove it in a later release.
• Changing parameters. Add new parameters with VALUE_DEFAULT rather than making them required. Top-level parameters cannot use VALUE_OPTIONAL.
• Adding a function to a built-in service. Listing MOODLE_OFFICIAL_MOBILE_SERVICE exposes the function to the Moodle App, so any app user's token can call it and its capability checks must be complete.

Common errors traced to services.php

Token errors from external clients have their own checklist in our Moodle invalid token guide, and the Moodle guide puts web services in the context of the wider plugin APIs.

Review checklist before release

1. Every function name starts with the plugin's frankenstyle component.
2. Every execute() calls validate_parameters(), validate_context() and require_capability(); the capabilities key lists the same capabilities.
3. ajax is true only for functions your JavaScript calls; loginrequired stays true unless the function is genuinely public.
4. Service keys and shortnames are unchanged from the previous release, or the upgrade notes tell administrators that tokens will be reissued.
5. The plugin version is bumped and the function appears under Site administration > Server > Web services > API Documentation.

How we can help

We build and review Moodle web service plugins, from function design and capability checks to upgrade-safe service definitions for integrations. See our Moodle development services or contact us about your integration.