version.php

Jump to: navigation, search

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 has been an exception for Activity modules. Before Moodle 2.6, $module-> was used instead of $plugin-> in the version.php file of this plugin type. Starting in Moodle 2.6, activity modules support the $plugin-> notation and it is recommended to use it. Support for $module-> will be dropped in Moodle 3.0. (MDL-43896)

Plugin version properties

Property Type Status Description and example
$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.

$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->cron integer optional Allows to throttle the plugin's cron function calls. If set to 0 or missing and the plugin's cron function exists, it is called on every cron.php execution. 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.

Note: 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->component string recommended The full frankenstyle compoment 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.
$plugin->component = 'block_foobar'; // Declare the type and name of this plugin.
$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:

<?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 2014, 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->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';
 
$plugin->dependencies = array(
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
);

See also