Note:

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

Plugin validation

From MoodleDocs
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Before a plugin can be made available via the Moodle Plugins directory it has to pass both an automatic and a manual validation process. The automatic checks are repeated for each new version of the plugin that is added, however the manual checks are only done for the initial release. The aim is to complete manual checks within three working days of first submission, but sometimes based on timing and/or allocation of resources, it can take longer than that, so please be patient.

The process

Plugin submission --> Waiting for approval --> Approved.
* Waiting for approval --> Needs more work --> Waiting for approval
** Click 'Schedule this plugin for re-approval' under 'Admin block' > '{your plugin}' > 'Schedule this plugin for re-approval' when ready to go back into the approval queue.

Note: Plugin approvers are always get notified on all plugins that aren't approved. Feel free to leave us messages in the plugin comments during this phase.

Automatic validation

General rules for all plugin types

  • Plugin name with Frankenstyle prefix must be unique in moodle.org/plugins. If there is another plugin with the same name you must either add new versions to this plugin (if it is yours) or rename your plugin if the names are accidentally the same. First in first served.
  • The plugin must be uploaded as a single zip file
  • The zip file must contain a single subfolder, named after your plugin (although the validator can also automatically rename subfolders generated by repos such as GitHub, which appear in the form 'username-moodle-pluginname-branchname')
  • The subfolder must be laid out in such a way that the uploaded file could be unzipped directly into the top-level folder for that plugin type (e.g. an activity plugin called 'myplugin' should install correctly when unzipped in the Moodle /mod folder, creating a subfolder /mod/myplugin with all the standard files within it).
  • The subfolder must contain a file called version.php. It should describe properties like 'version', 'requires', 'cron', 'component', 'maturity', 'release' and 'dependencies' . See exceptions below.
  • Language file must be present in lang/en/FULLNAME.php (for Moodle 2.0+) or lang/en_utf8/FULLNAME.php (for Moodle 1.9). FULLNAME is the plugin name with frankenstyle prefix. See exceptions below.
  • Language file must declare either $string['modulename'] (for activity modules) or $string['filtername'] (for Filters) or $string['pluginname'] (for all other plugin types). See exceptions below.
  • The names of all database tables should start with the full 'frankenstyle' plugin name. For example block_myblock, or auth_paypal. See exceptions for activity modules below.
  • The subfolder should contain a file called README.txt or README.md. (the validator can automatically rename other extensions to .txt) with details about the current release of the plugin.

Exceptions

  • version.php is required for Moodle 2.5 and onwards. It isn't strictly required (but it is always recommended) for older moodle versions for the following plugin types:
    • Themes for Moodle 2.0 to 2.4
    • Course formats for Moodle 2.0 to 2.4
    • Blocks for Moodle 1.9
    • Auth for Moodle 1.9
  • language file is not required for plugins for Moodle 1.9 that are not activity modules
  • $string['pluginname'] is not required for plugins for Moodle 1.9 that are not activity modules
  • Question types for Moodle versions <= 2.1 instead of $string['pluginname'] should declare $string[NAME] (where NAME is the name of the plugin without frankenstyle prefix). Starting from 2.2 this was fixed and $string['pluginname'] shall be used.
  • database tables should NOT use the "mod_" prefix for activity modules. They should just use the activity name as the prefix instead (e.g. "myplugin_").
  • database tables are allowed to have question_ prefix instead of qtype_ for Question types. This is for historical reasons, all newly developed plugins are encouraged to have qtype_ prefix.

Additional checks for activity modules

  • $module->version defined in version.php
  • $module->requires defined in version.php
  • file lib.php exists
  • file lib.php contains “function xxxx_add_instance”
  • file lib.php contains “function xxxx_update_instance”
  • file view.php exists
  • file index.php exists
  • db/install.xml exists
  • db/upgrade.php exists
  • db/access.php exists

Checks for particular plugin types

  • Themes: file config.php exists
  • Blocks: file block_xxxx.php exists
  • Auth: file auth.php exists
  • Course formats: file format.php exists

The Other category in the plugins directory

If your plugin does not yet meet all the different standards, you are encouraged to add it to the Moodle Plugins Directory Other category. Plugins in this category will be excluded from any automated processes such as installations or updates. Then when the plugin is improved to meet the standards, it can be moved to an another category in the plugins directory.

Manual checks

Before the plugin is publicly viewable a trusted reviewer will look through the code to make sure it is a valid plugin. These checks are completed by David Mudrak (Plugins Liaison, Moodle HQ) and Anthony Borrow (on a volunteer basis), so please bear with us if this sometimes takes a little longer than you expect. These checks include:

  • The plugin installs cleanly
  • It does not contain any obviously harmful code
  • It is not a spam entry (This is somewhat along the lines of the Moodle.org site policy too)
  • It does not duplicate an already uploaded plugin (or functionality available in core)
  • It mentions GPL license (if not a boilerplate atop every file then somewhere in the downloadable zip). (or be completely GPL compatible)
  • It has documentation and referenced URLs in basic english.
  • It does not lead to unrelated sites which can simply be linked to in content nor have unnecessarily repeated links.
  • Links that facilitate sharing (source control, issue tracker, documentation, discussion) are in the 'Useful links' section where possible.
  • Conventions are followed where possible. ( eg: https://docs.moodle.org/dev/Guidelines_for_contributed_code#How_to_submit_code)
  • Table config_plugin (not config) is used to store settings particular to a plugin.

Comments made during the review can usually be removed prior to approval if requested.

Recommended URLs

We usually request for the following data to be entered along with the plugin entry in order to facilitate easier sharing of information and feedback. So, in order of recommendation, they are :

  1. Code repository, this could be any publicly accessible code repository. The suggested naming convention of the repository is moodle-{plugintype}_{pluginname}.
    • Moodle development uses git almost 100% of the time as such lots of developers choose to have git repositories for their plugins too. There are popular public repositories, noteably github.com has some support on plugins directory for uploading of versions via a github repository plugin.
  2. Issue/Bug tracker. This is to enable users and other a quick link to easily report issues they encounter with your plugin.
    • You can choose to have a new component created in Tracker. You can also choose to have it elsewhere as long as it is publicly accessible. (See related discussion)
  3. Documentation. This could be at docs.moodle.org or anywhere publicly accessible.
  4. Website. This could be to demo, further describe or simply to link to one relevant page.

Other recommendations

  • Long and short descriptions are populated to allow for easy search/indexing of your plugin.

Frequently asked questions

Q: My code contains several components, why can't I distribute it as a single package?

A: Moodle's architecture supposes that plugins are installed independently. However you can contact Aparup or Anthony and ask for your plugins to be made into a set.

For versions from Moodle 2.2 onwards you can specify that one plugin depends on another in your version.php file.

Q: I don't know which Moodle plugin type I should use. Can I just make a 'local' plugin and get it done?

A: Most of the time there will be an applicable plugin type that will fit your add-on plugin. Using an appropriate plugin type allows you to use the relevant API and provide users with a common user interface throughout Moodle. This minimises work for you. The plugin will also be more easily understood by administrators and more people will use it.

We have seen that quite often a local plugin could actually have been an admin tool plugin, so consider if that is applicable in your case.

Here is the full list of plugins to choose from. If you think there is a need for a new plugin type, we're happy to consider API improvements.

For more information about Local plugins, see this clarification.

Q: I've a plugin to share that requires closed (or non-GPL compatible) source software. Can i share this in the plugins directory?

A: Yes you can but there are several things you must do to share this properly. Paraphrasing Martin, this is OK to be approved IF (and only if):

1) We give users FULL information on the dependency and what they need to do, in the description of the plugin.
2) We make it explicit that the required code is closed source and that we cannot vouch for it. The risks are all theirs to judge from wherever they obtain the software.

You can use the 'Potential privacy issues' field when editing the plugin to help describe this clearly.

Note: Your plugin must still satisfy other validations, such as not breaking moodle (without the required non-GPL software).

Q: How to help with language support to any plugin in the plugins directory?

A: Read this post for the procedure - http://lang.moodle.org/mod/forum/discuss.php?d=2485

See also

  • Plugin documentation for information on providing documentation for your plugin right here in docs.moodle.org
  • Plugin reviews for information on how to volunteer to write plugin reviews
  • Continuous integration with Travis-ci.