Skip to main content

Local plugins

The recommended way to add new functionality to Moodle is to create a new standard plugin (for example, activity, block, authentication, enrol). The local plugin-type is mostly suitable for things that do not fit into these standard plugin types.

Local plugins are used in cases when no standard plugin is suitable. Examples of these situations include:

  • event consumers communicating with external systems
  • custom definitions of web services and external functions
  • applications that extend moodle at the system level (for example hub server, amos server)
  • custom admin settings
  • extending the navigation block with custom menus
  • new database tables used in core hacks (strongly discouraged)
  • new capability definitions used in core hacks (strongly discouraged)

List of differences from normal plugins:​

Local plugins have several important differences from the standard plugin types, including:

  • they are always executed last during install, and upgrade. This is guaranteed by their order in get_plugin_types().
  • they are expected to use event handlers. Event subscriptions are intended for communication from core to plugins only, making local plugins the ideal candidate for them.
  • they can add admin settings to any settings page. They are loaded last when constructing admin tree to enable this.
  • they do not need to have any UI. Other plugin types are usually visible somewhere within the interface.

File structure​

Local plugins support the standard plugin files supported by other plugin types.

Examples​

The following examples show some ways in which you can use a local plugin.

Adding an element to the settings menu​

A local plugin can extend or modify the settings navigation by defining a function named local_[pluginname]_extend_settings_navigation in its lib.php. This is called when Moodle builds the settings block. For example:

Global plugin functions

Legacy
File path: /lib.php

The lib.php file is a legacy file which acts as a bridge between Moodle core, and the plugin. In recent plugins it is should only used to define callbacks and related functionality which currently is not supported as an auto-loadable class.

All functions defined in this file must meet the requirements set out in the relevant section of the Coding style.

Performance impact

Moodle core often loads all the lib.php files of a given plugin types. For performance reasons, it is strongly recommended to keep this file as small as possible and have just required code implemented in it. All the plugin's internal logic should be implemented in the auto-loaded classes.

View example
local/[pluginname]/lib.php
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Plugin functions for the local_[pluginname] plugin.
 *
 * @package   local_[pluginname]
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

function local_[pluginname]_extend_settings_navigation($settingsnav, $context) {
    global $CFG, $PAGE;

    // Only add this settings item on non-site course pages.
    if (!$PAGE->course or $PAGE->course->id == 1) {
        return;
    }

    // Only let users with the appropriate capability see this settings item.
    if (!has_capability('moodle/backup:backupcourse', context_course::instance($PAGE->course->id))) {
        return;
    }

    if ($settingnode = $settingsnav->find('courseadmin', navigation_node::TYPE_COURSE)) {
        $strfoo = get_string('foo', 'local_[pluginname]');
        $url = new moodle_url('/local/[pluginname]/foo.php', array('id' => $PAGE->course->id));
        $foonode = navigation_node::create(
            $strfoo,
            $url,
            navigation_node::NODETYPE_LEAF,
            '[pluginname]',
            '[pluginname]',
            new pix_icon('t/addcontact', $strfoo)
        );
        if ($PAGE->url->compare($url, URL_MATCH_BASE)) {
            $foonode->make_active();
        }
        $settingnode->add_node($foonode);
    }
}

A plugin can modify existing navigation, and settings navigation, components from within the local_[pluginname]_extend_navigation() function, for example:

Global plugin functions

Legacy
File path: /lib.php

The lib.php file is a legacy file which acts as a bridge between Moodle core, and the plugin. In recent plugins it is should only used to define callbacks and related functionality which currently is not supported as an auto-loadable class.

All functions defined in this file must meet the requirements set out in the relevant section of the Coding style.

Performance impact

Moodle core often loads all the lib.php files of a given plugin types. For performance reasons, it is strongly recommended to keep this file as small as possible and have just required code implemented in it. All the plugin's internal logic should be implemented in the auto-loaded classes.

View example
local/[pluginname]/lib.php
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Plugin functions for the local_[pluginname] plugin.
 *
 * @package   local_[pluginname]
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

function local_[pluginname]_extend_navigation(global_navigation $navigation) {
    if ($home = $navigation->find('home', global_navigation::TYPE_SETTING)) {
        $home->remove();
    }
}

Adding Site Wide Settings For Your Local Plugin​

Plugin settings

File path: /settings.php

You can define settings for your plugin that the administrator can configure by creating a settings.php file in the root of your plugins' directory.

caution

Settings must named in the following format:

plugintype_pluginname/settingname

By following the correct naming, all settings will automatically be stored in the config_plugins database table.

Full details on how to create settings are available in the Admin settings documentation.

View example
local/[pluginname]/settings.php
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Plugin settings for the local_[pluginname] plugin.
 *
 * @package   local_[pluginname]
 * @copyright Year, You Name <your@email.address>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

// Ensure the configurations for this site are set
if ($hassiteconfig) {

    // Create the new settings page
    // - in a local plugin this is not defined as standard, so normal $settings->methods will throw an error as
    // $settings will be null
    $settings = new admin_settingpage('local_[pluginname]', 'Your Settings Page Title');

    // Create
    $ADMIN->add('localplugins', $settings);

    // Add a setting field to the settings for this page
    $settings->add(new admin_setting_configtext(
        // This is the reference you will use to your configuration
        'local_[pluginname]/apikey',

        // This is the friendly title for the config, which will be displayed
        'External API: Key',

        // This is helper text for this config field
        'This is the key used to access the External API',

        // This is the default value
        'No Key Defined',

        // This is the type of Parameter this config is
        PARAM_TEXT
    ));
}