MoodleDocs - User contributions [en]

version.php

2020-01-23T05:55:12Z

Peterburnett: Changed incompatible. The commit message contained incorrect behaviour

This is an essential file expected to be located in the root directory of the plugin.

It contains a number of properties, which are used during the plugin installation and upgrade process. It allows to make sure the plugin is compatible with the given Moodle site, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' There was an exception for [[Activity modules]]. In the past, activity modules used <tt>$module-></tt> instead of <tt>$plugin-></tt> in their version.php files. The <tt>$plugin-></tt> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy <tt>$module-></tt> was dropped in Moodle 3.0 (MDL-43896).

'''Note:''' Support for <tt>$plugin->supported =</tt> and <tt>$plugin->incompatible =</tt> was added in Moodle 3.9 (MDL-59562).

== Plugin version properties ==

{| class="nicetable"
|-
! Property
! Type
! Status
! Description and example
|- style="vertical-align:top"
| style="min-width:200px" | '''$plugin->component'''
| string
| required<sup>*</sup>
| The full [[Frankenstyle|frankenstyle]] component name in the form of plugintype_pluginname. It is used during the installation and upgrade process for diagnostics and validation purposes to make sure the plugin code has been deployed to the correct location within the Moodle code tree.

<nowiki>*</nowiki>) Required since Moodle 3.0, strongly recommended for earlier versions (MDL-48494).

<code php>$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.</code>
|- style="vertical-align:top;"
| '''$plugin->version'''
| integer
| required
| The version number of the plugin. The format is partially date based with the form YYYYMMDDXX where XX is an incremental counter for the given year (YYYY), month (MM) and date (DD) of the plugin version's release. Every new plugin version must have this number increased in this file, which is detected by Moodle core and the upgrade process is triggered.

In case of linear development (i.e. there is just one branch of the plugin maintained), the XX counter should stay with the initial 00 value unless multiple versions are released on the same date.

If multiple stable branches of the plugin are maintained, the date part YYYYMMDD should be frozen at the branch forking date and the XX is used for incrementing the value on the given stable branch (allowing up to 100 updates on the given stable branch). The key point is that the version number is always increased both horizontally (within the same stable branch, more recent updates have higher XX than any previous one) and vertically (between any two stable branches, the more recent branch has YYYYMMDD00 higher than the older stable branch). Pay attention to this. It's easy to mess up and hard to fix.

See [https://moodle.org/mod/forum/discuss.php?d=275635#p1184986] for an example of versioning scheme on multiple branches.

<code php>$plugin->version = 2014052000; // Plugin released on 20th May 2014.</code>
|- style="vertical-align:top;"
| '''$plugin->requires'''
| integer
| recommended
| Specifies the minimum version number of Moodle core that this plugin requires. It is not possible to install it to earlier Moodle version. Moodle core's version number is defined in the file version.php located in Moodle root directory, in the <tt>$version</tt> variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as <tt>$version = 2014051200.01;</tt>). The decimal part is used for incremental (weekly) builds. Plugins should not rely on a particular weekly build so they use just the whole number part of the Moodle core's version in this field.

See [[Releases]] for the full list of Moodle core version numbers.

<code php>$plugin->requires = 2014051200; // Moodle 2.7.0 is required.</code>
|- style="vertical-align:top;"
| '''$plugin->supported'''
| array of two ascending integers
| optional
| Specifies a range of branch numbers of supported versions, inclusive. Moodle versions that are outside of this range will produce a message notifying at install time, but will allow for installation.

<code php>$plugin->supported = [37,39]; // Moodle 3.7.x, 3.8.x and 3.9.x are supported.</code>
|- style="vertical-align:top;"
| '''$plugin->incompatible'''
| integer
| optional
| Specifies the latest incompatible Moodle major branch. Any Moodle versions including and above this will be prevented from installing the plugin, and a message will be given when attempting installation.

<code php>$plugin->incompatible = 36; // Moodle 3.6.x and later are incompatible.</code>
|- style="vertical-align:top;"
| '''$plugin->cron'''
| integer
| discouraged*
| Allows to throttle the plugin's cron function calls. The set value represents a minimal required gap in seconds between two calls of the plugin's cron function. Note that the cron function is not supported in all plugin types (also note that, while the cron function '''is''' supported for authentication plugins, it is run every time the cron script runs, regardless of this value in version.php). This value is stored in the database. After changing this value, the version number must be incremented. For activity modules, if this value is not set or 0 the cron function is disabled.

<nowiki>*</nowiki>) Starting with Moodle 2.7, plugin developers are encouraged to use the [[Task API|scheduled task API]] instead of the cron function feature.

<code php>$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.</code>
|- style="vertical-align:top;"
| '''$plugin->maturity'''
| enum
| recommended
| Declares the maturity level of this plugin version, that is how stable it is. This affects the [[:en:Available update notifications|available update notifications]] feature in Moodle. Administrators can configure their site so that they are not notified about an available update unless it has certain maturity level declared.

Supported value is any of the predefined constants <tt>MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC</tt> or <tt>MATURITY_STABLE</tt>.

<code php>$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.</code>
|- style="vertical-align:top;"
| '''$plugin->release'''
| string
| recommended
| Human readable version name that should help to identify each release of the plugin. It can be anything you like although it is recommended to choose a pattern and stick with it. Usually it is a simple version like <tt>2.1</tt> but some plugin authors use more sophisticated schemes or follow the upstream release name if the plugin represents a wrapper for another program.

It is a good practise to tag the code in the source code management system for each plugin release and then make the tag names matching this release name.

<code php>$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.</code>
|- style="vertical-align:top;"
| '''$plugin->dependencies'''
| array
| optional
| Allows to declare explicit dependency on other plugin(s) for this plugin to work. Moodle core checks these declared dependencies and will not allow the plugin installation and/or upgrade until all dependencies are satisfied.

Each element in the array represents an dependency on another plugin. The key (string) in the array is the component (frankenstyle) name of the other plugin. The value (integer) is the version of the other plugin we require. The predefined constant <tt>ANY_VERSION</tt> can be used if we do not depend on a particular version (we just need the other plugin present).

<code php>$plugin->dependencies = array(
'mod_foo' => ANY_VERSION, // The Foo activity must be present (any version).
'enrol_bar' => 2014020300, // The Bar enrolment plugin version 2014020300 or higher must be present.
);</code>
|}

== File template ==

Here is a template for the plugin's version.php file to copy and paste:
<code 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/>.

/**
* @package plugintype_pluginname
* @copyright 2020, You Name <your@email.address>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO;
$plugin->supported = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->incompatible = TODO; // Available as of Moodle 3.9.0 or later.
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = [
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
];
</code>

== See also ==

* [[Moodle versions]]

[[Category:Plugins]]

Login callbacks

2019-10-15T04:29:01Z

Peterburnett: /* post_signup_requests */

There are cases where we want any plugin to do some check or action as part of the require_login check or related things around logging in or passwords but which are not handled by an authentication plugin.

== after_require_login ==

{{Moodle 3.7}}

This callback allow a plugin to add additional behavior after require_login is called. Some use cases:

* replacing the sitepolicy feature with a more robust / advanced version
* augmenting the 'user fully setup' workflow to add more steps but outside their profile editing page
* adding extra layers of checks, eg an ip address check but doing this across whole courses instead of at the sitelevel which is too coarse, or at the activity level which is too fine.
* enforcing various types of course visibility dependencies, eg 'before you can do course X you need to complete course Y'

<code>
function tool_myplugin_after_require_login() {
if (should_divert()) {
redirect($somewhere);
}
}
</code>

Implemented in https://tracker.moodle.org/browse/MDL-60470

== check_password_policy ==

{{Moodle 3.6}}

This callback allows a plugin to add additional password tests.

https://tracker.moodle.org/browse/MDL-61694

== print_password_policy ==

{{Moodle 3.8}}

This callback allows a plugin to explain the additional password added via check_password_policy

https://tracker.moodle.org/browse/MDL-66278

== pre_signup_requests ==

{{Moodle 3.5}}

eg to do actions before sign up such as acceptance of policies, validations, etc

<code>
function tool_myplugin_pre_signup_requests() {
// Do some special policy
}
</code>

https://tracker.moodle.org/browse/MDL-61485

== extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the change password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_change_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the set password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_set_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_forgot_password_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_signup_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_change_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_set_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_forgot_password_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_signup_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_change_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user changes their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_change_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_change_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_set_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user resets their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_set_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_set_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_forgot_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user submits a password reset request. This function is passed the submitted form data.

<code>
function tool_myplugin_post_forgot_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_forgot_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_signup_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user creates an account. This function is passed the submitted form data.

<code>
function tool_myplugin_post_signup_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_signup_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

Login callbacks

2019-10-15T04:28:48Z

Peterburnett: /* post_forgot_password_requests */

There are cases where we want any plugin to do some check or action as part of the require_login check or related things around logging in or passwords but which are not handled by an authentication plugin.

== after_require_login ==

{{Moodle 3.7}}

This callback allow a plugin to add additional behavior after require_login is called. Some use cases:

* replacing the sitepolicy feature with a more robust / advanced version
* augmenting the 'user fully setup' workflow to add more steps but outside their profile editing page
* adding extra layers of checks, eg an ip address check but doing this across whole courses instead of at the sitelevel which is too coarse, or at the activity level which is too fine.
* enforcing various types of course visibility dependencies, eg 'before you can do course X you need to complete course Y'

<code>
function tool_myplugin_after_require_login() {
if (should_divert()) {
redirect($somewhere);
}
}
</code>

Implemented in https://tracker.moodle.org/browse/MDL-60470

== check_password_policy ==

{{Moodle 3.6}}

This callback allows a plugin to add additional password tests.

https://tracker.moodle.org/browse/MDL-61694

== print_password_policy ==

{{Moodle 3.8}}

This callback allows a plugin to explain the additional password added via check_password_policy

https://tracker.moodle.org/browse/MDL-66278

== pre_signup_requests ==

{{Moodle 3.5}}

eg to do actions before sign up such as acceptance of policies, validations, etc

<code>
function tool_myplugin_pre_signup_requests() {
// Do some special policy
}
</code>

https://tracker.moodle.org/browse/MDL-61485

== extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the change password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_change_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the set password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_set_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_forgot_password_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_signup_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_change_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_set_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_forgot_password_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_signup_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_change_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user changes their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_change_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_change_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_set_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user resets their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_set_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_set_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_forgot_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user submits a password reset request. This function is passed the submitted form data.

<code>
function tool_myplugin_post_forgot_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_forgot_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_signup_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user creates an account. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_signup_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_signup_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

Login callbacks

2019-10-15T04:28:34Z

Peterburnett: /* post_set_password_requests */

There are cases where we want any plugin to do some check or action as part of the require_login check or related things around logging in or passwords but which are not handled by an authentication plugin.

== after_require_login ==

{{Moodle 3.7}}

This callback allow a plugin to add additional behavior after require_login is called. Some use cases:

* replacing the sitepolicy feature with a more robust / advanced version
* augmenting the 'user fully setup' workflow to add more steps but outside their profile editing page
* adding extra layers of checks, eg an ip address check but doing this across whole courses instead of at the sitelevel which is too coarse, or at the activity level which is too fine.
* enforcing various types of course visibility dependencies, eg 'before you can do course X you need to complete course Y'

<code>
function tool_myplugin_after_require_login() {
if (should_divert()) {
redirect($somewhere);
}
}
</code>

Implemented in https://tracker.moodle.org/browse/MDL-60470

== check_password_policy ==

{{Moodle 3.6}}

This callback allows a plugin to add additional password tests.

https://tracker.moodle.org/browse/MDL-61694

== print_password_policy ==

{{Moodle 3.8}}

This callback allows a plugin to explain the additional password added via check_password_policy

https://tracker.moodle.org/browse/MDL-66278

== pre_signup_requests ==

{{Moodle 3.5}}

eg to do actions before sign up such as acceptance of policies, validations, etc

<code>
function tool_myplugin_pre_signup_requests() {
// Do some special policy
}
</code>

https://tracker.moodle.org/browse/MDL-61485

== extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the change password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_change_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the set password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_set_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_forgot_password_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_signup_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_change_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_set_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_forgot_password_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_signup_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_change_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user changes their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_change_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_change_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_set_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user resets their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_set_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_set_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_forgot_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user submits a password reset request. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_forgot_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_forgot_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_signup_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user creates an account. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_signup_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_signup_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

Login callbacks

2019-10-15T04:28:19Z

Peterburnett: /* post_change_password_requests */

There are cases where we want any plugin to do some check or action as part of the require_login check or related things around logging in or passwords but which are not handled by an authentication plugin.

== after_require_login ==

{{Moodle 3.7}}

This callback allow a plugin to add additional behavior after require_login is called. Some use cases:

* replacing the sitepolicy feature with a more robust / advanced version
* augmenting the 'user fully setup' workflow to add more steps but outside their profile editing page
* adding extra layers of checks, eg an ip address check but doing this across whole courses instead of at the sitelevel which is too coarse, or at the activity level which is too fine.
* enforcing various types of course visibility dependencies, eg 'before you can do course X you need to complete course Y'

<code>
function tool_myplugin_after_require_login() {
if (should_divert()) {
redirect($somewhere);
}
}
</code>

Implemented in https://tracker.moodle.org/browse/MDL-60470

== check_password_policy ==

{{Moodle 3.6}}

This callback allows a plugin to add additional password tests.

https://tracker.moodle.org/browse/MDL-61694

== print_password_policy ==

{{Moodle 3.8}}

This callback allows a plugin to explain the additional password added via check_password_policy

https://tracker.moodle.org/browse/MDL-66278

== pre_signup_requests ==

{{Moodle 3.5}}

eg to do actions before sign up such as acceptance of policies, validations, etc

<code>
function tool_myplugin_pre_signup_requests() {
// Do some special policy
}
</code>

https://tracker.moodle.org/browse/MDL-61485

== extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the change password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_change_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the set password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_set_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_forgot_password_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_signup_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_change_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_set_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_forgot_password_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_signup_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_change_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user changes their password. This function is passed the submitted form data.

<code>
function tool_myplugin_post_change_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_change_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_set_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user resets their password. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_set_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_set_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_forgot_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user submits a password reset request. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_forgot_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_forgot_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_signup_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user creates an account. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_signup_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_signup_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

Callbacks

2019-10-15T04:27:37Z

Peterburnett:

Moodle does not have well-defined Hooks API but still allows plugins to hook into different processes by '''implementing callbacks'''. See also [[Communication Between Components]].

Some old APIs that were created before object-oriented programming use only callbacks. One of them is [[Activity modules]].

==Types of callbacks in Moodle==

=== Callback functions one-to-many ===

Core has a "hook point" where it allows plugins to execute some code, modify variables or return a result. Sometimes (especially for old callbacks) only plugins of a specific plugin type are allowed, however this is not recommended for the new callbacks because the list of callbacks is now cached and performance is not a constraint any more. If plugins want to implement the function for this callback they normally must place it in '''lib.php''' with the name '''pluginfullname_callbackname()'''. Here pluginname should be a full plugin name with a prefix, however activity modules can often omit the "mod_" prefix for historical reasons. Implementing this type of callback is optional and the "hook point" does not care how many and which plugins implement callback. Also "hook point" does not check if the plugin is enabled on this site, inside the callback plugins must check it themselves if it is important. Methods '''get_plugin_list_with_function()''' and '''get_plugins_with_function()''' are normally used in the "hook points" to find all plugins implementing a callback.

This document aims to cover ALL callbacks of this type that are present in Moodle core APIs or in standard Moodle plugins.

=== Callback functions one-to-one ===

Core API (or plugins such as blocks or reports) looks for and executes a method from the plugin/component that "owns" some entity, usually for checking permissions, pre-processing or providing the human-readable representation of this entity. Similar to one-to-many callbacks, the component/plugin must define a function with the name '''pluginfullname_callbackname()''' in lib.php . In some cases the function ''must'' be present or otherwise an exception is thrown or debugging message is displayed. Methods '''component_callback()''' and '''component_callback_exists()''' are normally used to find an implementation of a callback. Unlike one-to-many callbacks the implementing functions can exist not only in plugins but also in core components.

The list of one-to-one callbacks may not be 100% complete in this document, the aim is to cover the "magic" functions that are actually used despite IDE hints.

=== Other ===

* '''Files in the specific location'''. Core APIs may look for plugins that have a file with a specific file name, for example '''version.php''', '''settings.php''', '''styles.css''', '''module.js''', files in '''db/''' folder, etc. See [[Plugin files]]
* '''Event observers'''. Each plugin can implement event observers that execute code when event is triggered. See [[Event_2#Event_dispatching_and_observers|Events API]] about how to listen to events. Event observers can not always substitute callbacks because they do not return any value and can only happen in case of event. Many "hook points" are necessary before something has happened or when nothing is happening at all, for example a report/summary is gathered. However if it is possible to achieve the desired outcome with event observer, Moodle will not accept requests for adding a "hook point".
* Callbacks that are specified in the db/* file, for example in '''db/service.php''' developers must specify callback responsible for implementing web service, in '''db/tags.php''' developers specify callback for finding tagged items, etc. These types of callbacks are not covered on this page, information about them can be found in the respective APIs.

== Callbacks and external / webservices / consumers (mobile / apps) support ==

=== The problem ===

Our external functions are able to [[Web service API functions|perform a lot of actions]] against core. Those external functions use to implement their functionality reusing [[Core APIs]]. And, those APIs can contain hook points/callbacks to customize Moodle behavior.

Of course, ultimately, those external functions are used by the [[Web_services| web services layer]] providing all the functionality over REST/XMLRCP/SOAP "protocols". All those "clients" consuming Moodle Webservices (integrations in general, mobile & desktop apps...) should work ok, and we must guarantee that all the code executed in those underlying external functions (that may include hook points/callbacks) is supported by them.

In the other side, some of those callbacks may be focussed entirely in the web version of Moodle and have no application outside from there. Also, sometime, there are callbacks which goal is incompatible with uses from web service consumers, mainly because the consumers don't support this or that Moodle functionality used by the callback implementations.

Imagine a callback that provides to the consumer with something that it's not able to manage (say a mustache template, or a moodle form, or any other stuff in general that only core is able to provide). It's a pretty "possible" case a we need a way to handle it in an organised way.

=== The solution ===

To be able advance with those "problematic" hooks (not being supported by web-service consumers), it has been agreed to proceed with the following points in order to allow them to work via web, avoiding them to impact to consumers and registering the need of introducing (future) viable solutions to enable consumers to work with them.

All the following points must be considered as real requirements in order to allow a new callback (called from externals/web services) to land to core.

# '''Create a linked MOBILE issue''' requesting the callback to be supported in the app (for the record and future reference). Clearly explaining which are the externals / web services affected, what should be supported and, ideally, a way to provide that.
# '''Clearly indicate in the issue''' introducing the new callback if the hook is supported or not via WebServices. Callbacks documentation (below in this page) '''must include the comment''' ''"Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-xxxx and MOBILE-xxxx for more info."''" (where the MDL and MOBILE issues are the related ones).
# '''Add manual tests''' in the issue for checking that the related functionality in the mobile / desktop app is not broken and everything continues working ok.
# Check that the '''modified code or APIs does not impact on the external / WebServices''' API. You can just check if the modified function is used by the external API just adding a debug message and then running WebServices.
# If you need to add code in an API already used by the external API, you can always '''use the WS_SERVER constant''' to check if the current request comes from the external API to '''avoid its execution'''. With links to the correspoinding MDL-xxxx and MOBILE-xxxx issues.

== List of Moodle callbacks ==

=== List of one-to-many callbacks ===

To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

{| class="nicetable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Navigation, see [[Navigation API]]'''
|-
| extend_navigation_course
| *
|
| before Moodle 3.0 was only supported by ''report'' and ''tool'' plugin types
|-
| extend_settings_navigation
| local, booktool
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation
| local
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation_user_settings
| *
| 3.0+
| before Moodle 3.0 was only supported by ''tool'' plugin types
|-
| extend_navigation_category_settings
| *
| 3.0+
|
|-
| extend_navigation_frontpage
| *
| 3.1+
|
|-
| extend_navigation_user
| *
| 3.1+
|
|-
| colspan=4 align=center | '''Before-actions hooks'''
|-
| course_module_background_deletion_recommended
| *
| 3.2+
| see [https://github.com/moodle/moodle/blob/MOODLE_32_STABLE/lib/upgrade.txt#L142 upgrade.txt]
|-
| pre_block_delete
| *
| 3.1+
|
|-
| pre_course_category_delete
| *
| 3.1+
|
|-
| pre_course_delete
| *
| 3.1+
|
|-
| pre_course_module_delete
| *
| 3.1+
|
|-
| pre_user_delete
| *
| 3.1+
|
|-
| colspan=4 align=center | '''[[Login_callbacks]]'''
|-
| [[Login_callbacks#after_require_login | after_require_login]]
| *
| 3.7+
| eg Add permissions logic across a site or course
|-
| [[Login_callbacks#check_password_policy | check_password_policy]]
| *
| 3.6+
|
|-
| [[Login_callbacks#print_password_policy | print_password_policy]]
| *
| 3.8+ (WIP)
|
|-
| [[Login_callbacks#pre_signup_requests | pre_signup_requests]]
| *
| 3.5
| eg to do actions before sign up such as acceptance of policies, validations, etc
|-
| [[Login_callbacks#extend_change_password_form | extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_set_password_form | extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_forgot_password_form | extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_signup_form | extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_change_password_form | validate_extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_set_password_form | validate_extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_forgot_password_form | validate_extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_signup_form | validate_extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#post_change_password_requests | post_change_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user changes password.
|-
| [[Login_callbacks#post_set_password_requests | post_set_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user resets password.
|-
| [[Login_callbacks#post_forgot_password_requests | post_forgot_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user submits a password reset request.
|-
| [[Login_callbacks#post_signup_requests | post_signup_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user creates an account.
|-
| colspan=4 align=center | '''Page rendering, see [[Output_callbacks]]'''
|-
| [[Output_callbacks#add_htmlattributes | add_htmlattributes]]
| *
| 3.3+
| eg Add open graph xml namespace attributes
|-
| [[Output_callbacks#before_footer | before_footer]]
| *
| 3.3+
| eg injecting JS across the site, like analytics
|-
| [[Output_callbacks#before_http_headers | before_http_headers]]
| *
| 3.3+
| Setting http headers across the site like CSP
|-
| [[Output_callbacks#before_standard_html_head | before_standard_html_head]]

| *
| 3.3+
| An better API alternative to appending to $CFG->additionalhtmlhead
|-
| [[Output_callbacks#before_standard_top_of_body_html | before_standard_top_of_body_html]]
| *
| 3.3+
|
|-
| [[Output_callbacks#render_navbar_output | render_navbar_output]]
| *
| 3.2+
|
|-
| colspan=4 align=center | '''Course module edit form'''
|-
| coursemodule_edit_post_actions
| *
| 3.1+
|
|-
| coursemodule_standard_elements
| *
| 3.1+
|
|-
| coursemodule_validation
| *
| 3.1+
|
|-
| colspan=4 align=center | '''Modules'''
|-
| check_updates_since
| mod
| 3.2+
| See [[NEWMODULE_Documentation]]
|-
| dndupload_register
| mod
|
|
|-
| colspan=4 align=center | '''Other'''
|-
| get_fontawesome_icon_map
| *
| 3.3+
| https://docs.moodle.org/dev/Moodle_icons#Font_awesome_icons
|-
| get_question_bank_search_conditions
| local
|
|
|-
| oauth2_system_scopes
| *
| 3.3+
|
|-
| rss_get_feed
| *
|
|
|-
| supports_logstore
| report
|
|
|-
| get_shortcuts
| ltisource
| 3.1+
|
|-
| before_launch
| ltisource
| 2.8+
|
|-
| [[Miscellaneous_callbacks#control_view_profile | control_view_profile]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#store_profiling_data | store_profiling_data ]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#override_webservice_execution | override_webservice_execution]]
| *
| 3.6+
|
|-
| colspan=4 align=center | '''Deprecated'''
|-
| cron
| *
|
| See [[Task API]]
|-
| delete_course
| mod,report,coursereport,format
|
| Replace with observer to course_contents_deleted event
|-
| print_overview
| mod
| up to 3.2
| New dashboard uses [[Calendar API]] to populate events on the timeline
|-
| report_extend_navigation
| coursereport
|
| Plugin type ''coursereport'' is deprecated, plugin type ''report'' should be used instead
|}

'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions

=== List of one-to-one callbacks ===

To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

{| class="nicetable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Comments support''', see [[Comment API]]
|-
| comment_add
| *
|
|
|-
| comment_display
| *
|
|
|-
| comment_permissions
| *
|
|
|-
| comment_template
| *
|
|
|-
| comment_url
| *
|
|
|-
| comment_validate
| *
|
|
|-
| colspan=4 align=center | '''Gradebook'''
|-
| export_%_settings_definition
| gradeexport
|
| % is a plugin name ''without'' prefix
|-
| import_%_settings_definition
| gradeimport
|
| % is a plugin name ''without'' prefix
|-
| report_%_profilereport
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| report_%_settings_definition
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| colspan=4 align=center | '''Groups support''', see [[Groups API]]
|-
| allow_group_member_remove
| *
|
|
|-
| restore_group_member
| *
|
| For plugins that create their own groups
|-
| colspan=4 align=center | '''Installation and upgrade'''
|-
| xmldb_%_install
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_install_recovery
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_uninstall
| *
|
| Located in db/uninstall.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_upgrade
| *
|
| Located in db/upgrade.php , % refer to the full plugin name, in case of modules without prefix
|-
| colspan=4 align=center | '''LTI source'''
|-
| add_instance_hook
| ltisource
|
|
|-
| ''messagetype''
| ltisource
|
| Callback name is the type of the message
|-
| colspan=4 align=center | '''Question bank support''', see [[Question API]]
|-
| question_list_instances
| mod
|
|
|-
| question_pluginfile
| *
|
|
|-
| question_preview_pluginfile
| *
|
|
|-
| questions_in_use
| mod
|
|
|-
| colspan=4 align=center | '''Ratings support''', see [[Rating API]]
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_get_item_fields
| *
|
|
|-
| rating_permissions
| *
|
|
|-
| rating_validate
| *
|
|
|-
| colspan=4 align=center | '''Themes'''
|-
| $THEME->csspostprocess
| theme
|
|
|-
| $THEME->extralesscallback
| theme
|
|
|-
| $THEME->lessvariablescallback
| theme
|
|
|-
| page_init
| theme
|
|
|-
| colspan=4 align=center | '''Modules: Calendar and dashboard'''
|-
| core_calendar_event_action_shows_item_count
| mod
| 3.3+
|
|-
| core_calendar_is_event_visible
| mod
| 3.3+
|
|-
| core_calendar_provide_event_action
| mod
| 3.3+
|
|-
| colspan=4 align=center | '''Modules: Course cache'''
|-
| cm_info_dynamic
| mod
|
|
|-
| cm_info_view
| mod
|
|
|-
| get_coursemodule_info
| mod
|
|
|-
| colspan=4 align=center | '''Modules: Course reset'''
|-
| reset_course_form_defaults
| mod
|
|
|-
| reset_course_form_definition
| mod
|
|
|-
| reset_userdata
| mod
|
|
|-
| colspan=4 align=center | '''Modules'''
|-
| delete_instance
| mod
|
|
|-
| dndupload_handle
| mod
|
|
|-
| export_contents
| mod
|
| Used in WS get_course_contents
|-
| extend_settings_navigation
| mod,booktool
|
|
|-
| extends_navigation
| mod
|
|
|-
| get_completion_active_rule_descriptions
| mod
| 3.3+
| Must be present for modules implementing custom completion rules
|-
| get_completion_state
| mod
|
|
|-
| get_extra_capabilities
| mod
|
|
|-
| get_file_areas
| mod
|
|
|-
| get_recent_mod_activity
| mod
|
|
|-
| get_shortcuts
| mod
| 3.1+
|
|-
| grade_item_update
| mod
|
|
|-
| grading_areas_list
| mod
|
|
|-
| print_recent_activity
| mod
|
|
|-
| print_recent_mod_activity
| mod
|
|
|-
| refresh_events
| mod
|
|
|-
| rescale_activity_grades
| mod
| 3.1+
|
|-
| scale_used_anywhere
| mod
|
|
|-
| update_grades
| mod
|
|
|-
| user_complete
| mod
|
|
|-
| user_outline
| mod
|
|
|-
| colspan=4 align=center | '''Glossary formats'''
|-
| glossary_print_entry_%
| for glossary formats
|
| Glossary formats is not a plugin type yet, however the list of formats is not hardcoded in the mod_glossary, instead the methods similar to callbacks are used for each subfolder in mod/glossar/format. % refer to the subfolder name, the functions are expected in lib.php
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| colspan=4 align=center | '''Other'''
|-
| global_db_replace
| block
|
|
|-
| inplace_editable
| *
|
| See [[Inplace editable]]
|-
| output_fragment_*
| *
| 3.1+
| see [[Fragment]]
|-
| page_type_list
| *
|
| Used when displaying page types in block configuration
|-
| params_for_js
| atto
|
|
|-
| pluginfile
| *
|
| Callback checking permissions and preparing the file for serving plugin files, see [[File API]]. Note, in case of ''block'' plugins the list of arguments is slightly different
|-
| restore_role_assignment
| *
|
| For plugins that create their own role assignments
|-
| strings_for_js
| atto
|
|
|-
| supports
| *
|
| Required for activity modules
|-
| colspan=4 align=center | '''Deprecated'''
|-
| ajax_section_move
| format
| up to 2.3
| See [[Course formats]]
|-
| ajax_support
| format
| up to 2.3
| See [[Course formats]]
|-
| delete_course
| mod
| up to 3.1
| use event observer
|-
| display_content
| format
| up to 2.3
| See [[Course formats]]
|-
| get_post_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| get_section_name
| format
| up to 2.3
| See [[Course formats]]
|-
| get_section_url
| format
| up to 2.3
| See [[Course formats]]
|-
| get_types
| mod,ltisource
| up to 3.0
| Replaced with ''get_shortcuts'' in 3.1
|-
| get_view_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| load_content
| format
| up to 2.3
| See [[Course formats]]
|-
| scale_used
| mod
| up to 3.0
|
|-
| uses_sections
| format
| up to 2.3
| See [[Course formats]]
|}

'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions

== Adding new callbacks to core ==

If you are preparing a patch for core which adds a new callback here are some things which should be considered.

TBA see https://tracker.moodle.org/browse/MDL-60510

Login callbacks

2019-10-03T00:56:45Z

Peterburnett:

There are cases where we want any plugin to do some check or action as part of the require_login check or related things around logging in or passwords but which are not handled by an authentication plugin.

== after_require_login ==

{{Moodle 3.7}}

This callback allow a plugin to add additional behavior after require_login is called. Some use cases:

* replacing the sitepolicy feature with a more robust / advanced version
* augmenting the 'user fully setup' workflow to add more steps but outside their profile editing page
* adding extra layers of checks, eg an ip address check but doing this across whole courses instead of at the sitelevel which is too coarse, or at the activity level which is too fine.
* enforcing various types of course visibility dependencies, eg 'before you can do course X you need to complete course Y'

<code>
function tool_myplugin_after_require_login() {
if (should_divert()) {
redirect($somewhere);
}
}
</code>

Implemented in https://tracker.moodle.org/browse/MDL-60470

== check_password_policy ==

{{Moodle 3.6}}

This callback allows a plugin to add additional password tests.

https://tracker.moodle.org/browse/MDL-61694

== print_password_policy ==

{{Moodle 3.8}}

This callback allows a plugin to explain the additional password added via check_password_policy

https://tracker.moodle.org/browse/MDL-66278

== pre_signup_requests ==

{{Moodle 3.5}}

eg to do actions before sign up such as acceptance of policies, validations, etc

<code>
function tool_myplugin_pre_signup_requests() {
// Do some special policy
}
</code>

https://tracker.moodle.org/browse/MDL-61485

== extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the change password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_change_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the set password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_set_password_form($mform, $user) {
// Inject a static element of the user's username
$mform->addElement('static', 'injectedstatic', $user->username);
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_forgot_password_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for injection of additional form elements into the forgot password form, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_extend_signup_form($mform) {
// Inject a static element of the word 'injected'
$mform->addElement('static', 'injectedstatic', 'injected');
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_change_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_change_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_set_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_set_password_form($data, $user) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_forgot_password_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_forgot_password_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== validate_extend_signup_form ==

{{Moodle 3.8}}

WIP: This callback allows for additional validation of existing and additional form elements, to allow for more complicated behaviour such as 2FA.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_validate_extend_signup_form($data) {
// Validate that an injected elements equals the word 'test'
$errors = array();
if ($data['injectedtext'] != 'test') {
$errors['injectedtext'] = 'wrong';
}
return $errors;
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_change_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user changes their password. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_change_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_change_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_set_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user resets their password. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_set_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_set_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_forgot_password_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user submits a password reset request. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_forgot_password_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_forgot_password_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

== post_signup_requests ==

{{Moodle 3.8}}

WIP: Fire any additional actions required after a user creates an account. This function is passed the submitted form data.
Note: This hook is not supported or compatible with the Webservices API or the Moodle mobile app. It does not damage or interrupt any current functionality of the mobile application, however injected form elements and actions will not be executed for mobile users.

<code>
function tool_myplugin_post_signup_requests($data) {
// Display a popup message that echoes what a user submitted in an injected element
$message = ('post_signup_request - Input: '.$data->injectedtext);
echo "<script type='text/javascript'>alert('$message');</script>";
}
</code>

https://tracker.moodle.org/browse/MDL-66173

Callbacks

2019-10-03T00:14:05Z

Peterburnett: /* List of one-to-many callbacks */

Moodle does not have well-defined Hooks API but still allows plugins to hook into different processes by '''implementing callbacks'''. See also [[Communication Between Components]].

Some old APIs that were created before object-oriented programming use only callbacks. One of them is [[Activity modules]].

==Types of callbacks in Moodle==

=== Callback functions one-to-many ===

Core has a "hook point" where it allows plugins to execute some code, modify variables or return a result. Sometimes (especially for old callbacks) only plugins of a specific plugin type are allowed, however this is not recommended for the new callbacks because the list of callbacks is now cached and performance is not a constraint any more. If plugins want to implement the function for this callback they normally must place it in '''lib.php''' with the name '''pluginfullname_callbackname()'''. Here pluginname should be a full plugin name with a prefix, however activity modules can often omit the "mod_" prefix for historical reasons. Implementing this type of callback is optional and the "hook point" does not care how many and which plugins implement callback. Also "hook point" does not check if the plugin is enabled on this site, inside the callback plugins must check it themselves if it is important. Methods '''get_plugin_list_with_function()''' and '''get_plugins_with_function()''' are normally used in the "hook points" to find all plugins implementing a callback.

This document aims to cover ALL callbacks of this type that are present in Moodle core APIs or in standard Moodle plugins.

=== Callback functions one-to-one ===

Core API (or plugins such as blocks or reports) looks for and executes a method from the plugin/component that "owns" some entity, usually for checking permissions, pre-processing or providing the human-readable representation of this entity. Similar to one-to-many callbacks, the component/plugin must define a function with the name '''pluginfullname_callbackname()''' in lib.php . In some cases the function ''must'' be present or otherwise an exception is thrown or debugging message is displayed. Methods '''component_callback()''' and '''component_callback_exists()''' are normally used to find an implementation of a callback. Unlike one-to-many callbacks the implementing functions can exist not only in plugins but also in core components.

The list of one-to-one callbacks may not be 100% complete in this document, the aim is to cover the "magic" functions that are actually used despite IDE hints.

=== Other ===

* '''Files in the specific location'''. Core APIs may look for plugins that have a file with a specific file name, for example '''version.php''', '''settings.php''', '''styles.css''', '''module.js''', files in '''db/''' folder, etc. See [[Plugin files]]
* '''Event observers'''. Each plugin can implement event observers that execute code when event is triggered. See [[Event_2#Event_dispatching_and_observers|Events API]] about how to listen to events. Event observers can not always substitute callbacks because they do not return any value and can only happen in case of event. Many "hook points" are necessary before something has happened or when nothing is happening at all, for example a report/summary is gathered. However if it is possible to achieve the desired outcome with event observer, Moodle will not accept requests for adding a "hook point".
* Callbacks that are specified in the db/* file, for example in '''db/service.php''' developers must specify callback responsible for implementing web service, in '''db/tags.php''' developers specify callback for finding tagged items, etc. These types of callbacks are not covered on this page, information about them can be found in the respective APIs.

== List of Moodle callbacks ==

=== List of one-to-many callbacks ===

To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

{| class="nicetable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Navigation, see [[Navigation API]]'''
|-
| extend_navigation_course
| *
|
| before Moodle 3.0 was only supported by ''report'' and ''tool'' plugin types
|-
| extend_settings_navigation
| local, booktool
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation
| local
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation_user_settings
| *
| 3.0+
| before Moodle 3.0 was only supported by ''tool'' plugin types
|-
| extend_navigation_category_settings
| *
| 3.0+
|
|-
| extend_navigation_frontpage
| *
| 3.1+
|
|-
| extend_navigation_user
| *
| 3.1+
|
|-
| colspan=4 align=center | '''Before-actions hooks'''
|-
| course_module_background_deletion_recommended
| *
| 3.2+
| see [https://github.com/moodle/moodle/blob/MOODLE_32_STABLE/lib/upgrade.txt#L142 upgrade.txt]
|-
| pre_block_delete
| *
| 3.1+
|
|-
| pre_course_category_delete
| *
| 3.1+
|
|-
| pre_course_delete
| *
| 3.1+
|
|-
| pre_course_module_delete
| *
| 3.1+
|
|-
| pre_user_delete
| *
| 3.1+
|
|-
| colspan=4 align=center | '''[[Login_callbacks]]'''
|-
| [[Login_callbacks#after_require_login | after_require_login]]
| *
| 3.7+
| eg Add permissions logic across a site or course
|-
| [[Login_callbacks#check_password_policy | check_password_policy]]
| *
| 3.6+
|
|-
| [[Login_callbacks#print_password_policy | print_password_policy]]
| *
| 3.8+ (WIP)
|
|-
| [[Login_callbacks#pre_signup_requests | pre_signup_requests]]
| *
| 3.5
| eg to do actions before sign up such as acceptance of policies, validations, etc
|-
| [[Login_callbacks#extend_change_password_form | extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#extend_set_password_form | extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#extend_forgot_password_form | extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#extend_signup_form | extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#validate_extend_change_password_form | validate_extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#validate_extend_set_password_form | validate_extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#validate_extend_forgot_password_form | validate_extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#validate_extend_signup_form | validate_extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#post_change_password_requests | post_change_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user changes password. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#post_set_password_requests | post_set_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user resets password. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#post_forgot_password_requests | post_forgot_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user submits a password reset request. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| [[Login_callbacks#post_signup_requests | post_signup_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user creates an account. Note: This hook is not compatible with the Webservices API or the Moodle mobile app.
|-
| colspan=4 align=center | '''Page rendering, see [[Output_callbacks]]'''
|-
| [[Output_callbacks#add_htmlattributes | add_htmlattributes]]
| *
| 3.3+
| eg Add open graph xml namespace attributes
|-
| [[Output_callbacks#before_footer | before_footer]]
| *
| 3.3+
| eg injecting JS across the site, like analytics
|-
| [[Output_callbacks#before_http_headers | before_http_headers]]
| *
| 3.3+
| Setting http headers across the site like CSP
|-
| [[Output_callbacks#before_standard_html_head | before_standard_html_head]]

| *
| 3.3+
| An better API alternative to appending to $CFG->additionalhtmlhead
|-
| [[Output_callbacks#before_standard_top_of_body_html | before_standard_top_of_body_html]]
| *
| 3.3+
|
|-
| [[Output_callbacks#render_navbar_output | render_navbar_output]]
| *
| 3.2+
|
|-
| colspan=4 align=center | '''Course module edit form'''
|-
| coursemodule_edit_post_actions
| *
| 3.1+
|
|-
| coursemodule_standard_elements
| *
| 3.1+
|
|-
| coursemodule_validation
| *
| 3.1+
|
|-
| colspan=4 align=center | '''Modules'''
|-
| check_updates_since
| mod
| 3.2+
| See [[NEWMODULE_Documentation]]
|-
| dndupload_register
| mod
|
|
|-
| colspan=4 align=center | '''Other'''
|-
| get_fontawesome_icon_map
| *
| 3.3+
| https://docs.moodle.org/dev/Moodle_icons#Font_awesome_icons
|-
| get_question_bank_search_conditions
| local
|
|
|-
| oauth2_system_scopes
| *
| 3.3+
|
|-
| rss_get_feed
| *
|
|
|-
| supports_logstore
| report
|
|
|-
| get_shortcuts
| ltisource
| 3.1+
|
|-
| before_launch
| ltisource
| 2.8+
|
|-
| [[Miscellaneous_callbacks#control_view_profile | control_view_profile]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#store_profiling_data | store_profiling_data ]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#override_webservice_execution | override_webservice_execution]]
| *
| 3.6+
|
|-
| colspan=4 align=center | '''Deprecated'''
|-
| cron
| *
|
| See [[Task API]]
|-
| delete_course
| mod,report,coursereport,format
|
| Replace with observer to course_contents_deleted event
|-
| print_overview
| mod
| up to 3.2
| New dashboard uses [[Calendar API]] to populate events on the timeline
|-
| report_extend_navigation
| coursereport
|
| Plugin type ''coursereport'' is deprecated, plugin type ''report'' should be used instead
|}

'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions

=== List of one-to-one callbacks ===

To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.

{| class="nicetable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Comments support''', see [[Comment API]]
|-
| comment_add
| *
|
|
|-
| comment_display
| *
|
|
|-
| comment_permissions
| *
|
|
|-
| comment_template
| *
|
|
|-
| comment_url
| *
|
|
|-
| comment_validate
| *
|
|
|-
| colspan=4 align=center | '''Gradebook'''
|-
| export_%_settings_definition
| gradeexport
|
| % is a plugin name ''without'' prefix
|-
| import_%_settings_definition
| gradeimport
|
| % is a plugin name ''without'' prefix
|-
| report_%_profilereport
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| report_%_settings_definition
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| colspan=4 align=center | '''Groups support''', see [[Groups API]]
|-
| allow_group_member_remove
| *
|
|
|-
| restore_group_member
| *
|
| For plugins that create their own groups
|-
| colspan=4 align=center | '''Installation and upgrade'''
|-
| xmldb_%_install
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_install_recovery
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_uninstall
| *
|
| Located in db/uninstall.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_upgrade
| *
|
| Located in db/upgrade.php , % refer to the full plugin name, in case of modules without prefix
|-
| colspan=4 align=center | '''LTI source'''
|-
| add_instance_hook
| ltisource
|
|
|-
| ''messagetype''
| ltisource
|
| Callback name is the type of the message
|-
| colspan=4 align=center | '''Question bank support''', see [[Question API]]
|-
| question_list_instances
| mod
|
|
|-
| question_pluginfile
| *
|
|
|-
| question_preview_pluginfile
| *
|
|
|-
| questions_in_use
| mod
|
|
|-
| colspan=4 align=center | '''Ratings support''', see [[Rating API]]
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_get_item_fields
| *
|
|
|-
| rating_permissions
| *
|
|
|-
| rating_validate
| *
|
|
|-
| colspan=4 align=center | '''Themes'''
|-
| $THEME->csspostprocess
| theme
|
|
|-
| $THEME->extralesscallback
| theme
|
|
|-
| $THEME->lessvariablescallback
| theme
|
|
|-
| page_init
| theme
|
|
|-
| colspan=4 align=center | '''Modules: Calendar and dashboard'''
|-
| core_calendar_event_action_shows_item_count
| mod
| 3.3+
|
|-
| core_calendar_is_event_visible
| mod
| 3.3+
|
|-
| core_calendar_provide_event_action
| mod
| 3.3+
|
|-
| colspan=4 align=center | '''Modules: Course cache'''
|-
| cm_info_dynamic
| mod
|
|
|-
| cm_info_view
| mod
|
|
|-
| get_coursemodule_info
| mod
|
|
|-
| colspan=4 align=center | '''Modules: Course reset'''
|-
| reset_course_form_defaults
| mod
|
|
|-
| reset_course_form_definition
| mod
|
|
|-
| reset_userdata
| mod
|
|
|-
| colspan=4 align=center | '''Modules'''
|-
| delete_instance
| mod
|
|
|-
| dndupload_handle
| mod
|
|
|-
| export_contents
| mod
|
| Used in WS get_course_contents
|-
| extend_settings_navigation
| mod,booktool
|
|
|-
| extends_navigation
| mod
|
|
|-
| get_completion_active_rule_descriptions
| mod
| 3.3+
| Must be present for modules implementing custom completion rules
|-
| get_completion_state
| mod
|
|
|-
| get_extra_capabilities
| mod
|
|
|-
| get_file_areas
| mod
|
|
|-
| get_recent_mod_activity
| mod
|
|
|-
| get_shortcuts
| mod
| 3.1+
|
|-
| grade_item_update
| mod
|
|
|-
| grading_areas_list
| mod
|
|
|-
| print_recent_activity
| mod
|
|
|-
| print_recent_mod_activity
| mod
|
|
|-
| refresh_events
| mod
|
|
|-
| rescale_activity_grades
| mod
| 3.1+
|
|-
| scale_used_anywhere
| mod
|
|
|-
| update_grades
| mod
|
|
|-
| user_complete
| mod
|
|
|-
| user_outline
| mod
|
|
|-
| colspan=4 align=center | '''Glossary formats'''
|-
| glossary_print_entry_%
| for glossary formats
|
| Glossary formats is not a plugin type yet, however the list of formats is not hardcoded in the mod_glossary, instead the methods similar to callbacks are used for each subfolder in mod/glossar/format. % refer to the subfolder name, the functions are expected in lib.php
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| colspan=4 align=center | '''Other'''
|-
| global_db_replace
| block
|
|
|-
| inplace_editable
| *
|
| See [[Inplace editable]]
|-
| output_fragment_*
| *
| 3.1+
| see [[Fragment]]
|-
| page_type_list
| *
|
| Used when displaying page types in block configuration
|-
| params_for_js
| atto
|
|
|-
| pluginfile
| *
|
| Callback checking permissions and preparing the file for serving plugin files, see [[File API]]. Note, in case of ''block'' plugins the list of arguments is slightly different
|-
| restore_role_assignment
| *
|
| For plugins that create their own role assignments
|-
| strings_for_js
| atto
|
|
|-
| supports
| *
|
| Required for activity modules
|-
| colspan=4 align=center | '''Deprecated'''
|-
| ajax_section_move
| format
| up to 2.3
| See [[Course formats]]
|-
| ajax_support
| format
| up to 2.3
| See [[Course formats]]
|-
| delete_course
| mod
| up to 3.1
| use event observer
|-
| display_content
| format
| up to 2.3
| See [[Course formats]]
|-
| get_post_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| get_section_name
| format
| up to 2.3
| See [[Course formats]]
|-
| get_section_url
| format
| up to 2.3
| See [[Course formats]]
|-
| get_types
| mod,ltisource
| up to 3.0
| Replaced with ''get_shortcuts'' in 3.1
|-
| get_view_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| load_content
| format
| up to 2.3
| See [[Course formats]]
|-
| scale_used
| mod
| up to 3.0
|
|-
| uses_sections
| format
| up to 2.3
| See [[Course formats]]
|}

'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions

== Adding new callbacks to core ==

If you are preparing a patch for core which adds a new callback here are some things which should be considered.

TBA see https://tracker.moodle.org/browse/MDL-60510

Callbacks

2019-06-26T23:37:44Z

Peterburnett: Added check_password_policy in moodlelib.php, from version 3.6