If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.


From MoodleDocs
Revision as of 13:04, 17 August 2022 by Dev Docs Bot (talk | contribs) (Update migration status and path)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

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 $module-> instead of $plugin-> in their version.php files. The $plugin-> notation support for activity modules was added in Moodle 2.5 (MDL-38121) and became recommended. Support for legacy $module-> was dropped in Moodle 3.0 (MDL-43896).

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

Plugin version properties

Property Type Status Description and example
$plugin->component string required* The full 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.

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

$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.
$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 [1] for an example of versioning scheme on multiple branches.

$plugin->version = 2014052000; // Plugin released on 20th May 2014.
$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 $version variable.

Note that Moodle core extends the version numbering scheme and has inbuilt support for decimal versioning (such as $version = 2014051200.01;). 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.

$plugin->requires = 2014051200; // Moodle 2.7.0 is required.
$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.

$plugin->supported = [37, 39]; // Moodle 3.7.x, 3.8.x and 3.9.x are supported.
$plugin->incompatible integer optional Specifies the earliest 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.

$plugin->incompatible = 36; // Moodle 3.6.x and later are incompatible.
$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.

*) Starting with Moodle 2.7, plugin developers are encouraged to use the scheduled task API instead of the cron function feature.

$plugin->cron = 300; // Do not execute this plugin's cron more often than every five minutes.
$plugin->maturity enum recommended Declares the maturity level of this plugin version, that is how stable it is. This affects the 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 MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC or MATURITY_STABLE.

$plugin->maturity = MATURITY_STABLE; // This is considered as ready for production sites.
$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 2.1 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.

$plugin->release = 'v2.7-r1'; // This is our first revision for Moodle 2.7.x branch.
$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 ANY_VERSION can be used if we do not depend on a particular version (we just need the other plugin present).

$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.

File template

Here is a template for the plugin's version.php file to copy and paste:

// This file is part of Moodle -
// 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
// 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 <>.

 * @package   plugintype_pluginname
 * @copyright 2020, You Name <your@email.address>
 * @license 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

See also