Plugin files: Difference between revisions

Latest revision as of 12:08, 28 June 2022

Important:

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!

The following is a list of files that work the same in all plugin types (if they are present).

version.php

Meta-data about the plugin (like the version number, dependencies or the maturity level) are defined here.

version.php page provides detailed description of the file contents

lang/en/plugintype_pluginname.php

English strings for the plugin are defined here. At least $string['pluginname'] must be present. There is an exception for the Activity modules, their expected file name is just pluginname.php (without the mod_ prefix).

String API provides information about the string files

lib.php

The interface between the Moodle core and the plugin is defined here for the most plugin types. The expected contents of the file depends on the particular plugin type.

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

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

Coding style#Functions and Methods

locallib.php

The use of this file is no longer recommended, and will not be permitted in core code. Rather than creating global function in a global namespace in a locallib.php file, you should make use of autoloaded classes which are located in the classes/ directory.

No new additions to this file will be permitted in Moodle core.

Where this file is in use, all functions must meet the requirements set out in the relevant section of the Coding style

Existing functions which have been incorreclty named will not be accepted as an example of an existing convention. Existing functions which are incorrectly named should be converted to use a namespaced class.

db/install.xml

The plugin's database scheme (tables, fields, indexes and keys) are defined here. You should always use the in-built XMLDB editor to generate this file.

XMLDB Documentation

db/upgrade.php

Upgrade steps (such as database scheme changes and other things that must happen when the plugin is being upgraded) are defined here. The in-built XMLDB editor can be used to generate the code to change the database scheme.

Upgrade API

db/access.php

Plugin capabilities are defined here.

Access_API

db/install.php

Allows you to execute a PHP code right after the plugin's database scheme has been installed.

db/uninstall.php

Allows you to execute a PHP code before the plugin's database tables and data are dropped during the plugin uninstallation.

db/events.php

Event handlers (subscriptions) are defined here. It lists all the events that your plugin want to observe and be notified about.

Events API

db/messages.php

Allow to declare your plugin as the messaging provider.

Message API

db/services.php

External functions and web services provided by your plugin are described here.

db/renamedclasses.php

Details of classes that have been renamed to fit in with autoloading. See forum discussion for details.

Please note that the new classname must exist and should not be prefixed with a leading backslash.

<?php

defined('MOODLE_INTERNAL') || die;

$renamedclasses = [
    // Format:
    'old_class_name' => 'fully_qualified\\new\\name',

    // Examples:
    'assign_header' => 'mod_assign\\output\\header',
    '\assign_header' => 'mod_assign\\output\\header',
    '\assign' => 'mod_assign\\assignment',

    // Bad:
    'assign_header' => '\\mod_assign\\output\\header',
];

classes/

cli/

It is a convention in the Moodle code that all CLI scripts are put into the cli/ folder inside the plugin directory. Make sure all these files declare themselves as CLI scripts properly (the constant must be defined prior to loading the config.php):

define('CLI_SCRIPT', true);
require(__DIR__.'/../../../config.php');
require_once($CFG->libdir.'/clilib.php');

settings.php

Describes the administration configuration for your plugin.

The setting names are supposed to be plugintype_pluginname/settingname (note the slash) and not plugintype_pluginname_settingname or even just settingname. This makes them to be stored in the config_plugins table without polluting the global $CFG object.

Admin settings

amd/

Plugin's Javascript modules written using AMD or ES6 format. (AMD, supported since Moodle 2.9, ES6 since Moodle 3.8).

Note: Since Moodle 3.9, all files must be in an ES6 format for acceptance into core.

Javascript Modules

yui/

Plugin's YUI modules (recommended way to include Javascript in Moodle 2.8 and older).

Note: The inclusion of new YUI modules will not be accepted to Moodle core from Moodle 3.8 onwards with the exception of Atto Editor plugins.

jquery/

Plugin's jQuery modules (Moodle 2.8 and older)

Note: The inclusion of jQuery modules will not be accepted to Moodle core from Moodle 2.9 onwards.

jQuery pre2.9

styles.css

The plugin's CSS are stored here.

pix/icon.svg

The plugin's icon. Activity modules should provide 24 x 24 px colour icons. All other plugin files should be represented by 16 x 16 px monochrome icon. There should be a fallback pix/icon.png version of the icon for legacy browsers.

Moodle icons provides icons design guidelines

thirdpartylibs.xml

The file should list all 3rd party libraries bundled with a plugin.

<?xml version="1.0"?>
<libraries>
    <library>
        <location>javascript/html5shiv.js</location>
        <name>Html5Shiv</name>
        <version>3.6.2</version>
        <license>Apache</license>
        <licenseversion>2.0</licenseversion>
    </library>
    <library>
        <location>vendor/guzzle/guzzle/</location>
        <name>guzzle</name>
        <version>v3.9.3</version>
        <license>MIT</license>
        <licenseversion></licenseversion>
    </library>
</libraries>

The location is a path to the library directory or file, relative to the plugin's root directory. Please note that license must be always compatible with the GNU GPLv3.

Locations defined in this file are excluded from the coding style prechecks that are executed during the Plugin validation.

More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries

readme_moodle.txt

The file should contain detailed instructions on how to import 3rd party libraries into Moodle. This should list:

Download URLs
Build instructions

More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries

environment.xml

Plugin can declare its additional environment requirements via this file - such as compulsory presence of some otherwise optional PHP extension. See Environment checking#Configuration file overview for details of the syntax.

<?xml version="1.0" encoding="UTF-8" ?>
<COMPATIBILITY_MATRIX>
  <PLUGIN name="plugintype_pluginname">
    <PHP_EXTENSIONS>
      <PHP_EXTENSION name="soap" level="required">
      </PHP_EXTENSION>
    </PHP_EXTENSIONS>
  </PLUGIN>
</COMPATIBILITY_MATRIX>

README

The file README.md or README.txt should contain useful information about the plugin. Ideally, it should act as an offline version of all the informations that are available at the plugin's page in the Plugins directory.

CHANGES

If the file CHANGES.md (or CHANGES.txt, CHANGES.html or just CHANGES alternatively) is found when uploading a new plugin version into the Plugins directory, then the contents of this file is used to pre-fill the release notes field for the new version.

Documentation

Plugin files: Difference between revisions

Latest revision as of 12:08, 28 June 2022

Contents

version.php

lang/en/plugintype_pluginname.php

lib.php

locallib.php

db/install.xml

db/upgrade.php

db/access.php

db/install.php

db/uninstall.php

db/events.php

db/messages.php

db/services.php

db/renamedclasses.php

classes/

cli/

settings.php

amd/

yui/

jquery/

styles.css

pix/icon.svg

thirdpartylibs.xml

readme_moodle.txt

environment.xml

README

CHANGES

See also

@@ Line 1: / Line 1: @@
+{{Template:Migrated|newDocId=/docs/apis/commonfiles}}
 {{Plugins development}}
 The following is a list of files that work the same in all [[Plugin types|plugin types]] (if they are present).
 === version.php ===
 Meta-data about the plugin (like the version number, dependencies or the maturity level) are defined here.
 * [[version.php]] page provides detailed description of the file contents
 === lang/en/plugintype_pluginname.php ===
 English strings for the plugin are defined here. At least <tt>$string['pluginname']</tt> must be present. There is an exception for the [[Activity modules]], their expected file name is just <tt>pluginname.php</tt> (without the <tt>mod_</tt> prefix).
 * [[String API]] provides information about the string files
 === lib.php ===
 The interface between the Moodle core and the plugin is defined here for the most plugin types. The expected contents of the file depends on the particular plugin type.
@@ Line 22: / Line 14: @@
 All functions defined in this file ''must'' meet the requirements set out in the relevant section of the [[Coding style#Functions and Methods|Coding style]]
 * [[Coding style#Functions and Methods]]
 === locallib.php ===
 The use of this file is no longer recommended, and will not be permitted in core code. Rather than creating global function in a global namespace in a <tt>locallib.php</tt> file, you should make use of autoloaded classes which are located in the <tt>classes/</tt> directory.
@@ Line 34: / Line 23: @@
 Existing functions which have been incorreclty named ''will not'' be accepted as an example of an existing convention. Existing functions which are incorrectly named ''should'' be converted to use a namespaced class.
 === db/install.xml ===
 The plugin's database scheme (tables, fields, indexes and keys) are defined here. You should always use the in-built XMLDB editor to generate this file.
 * [[XMLDB Documentation]]
 === db/upgrade.php ===
 Upgrade steps (such as database scheme changes and other things that must happen when the plugin is being upgraded) are defined here. The in-built [[XMLDB]] editor can be used to generate the code to change the database scheme.
 * [[Upgrade API]]
 === db/access.php ===
 Plugin capabilities are defined here.
 * [[Access_API]]
 === db/install.php ===
 Allows you to execute a PHP code right after the plugin's database scheme has been installed.
 === db/uninstall.php ===
 Allows you to execute a PHP code before the plugin's database tables and data are dropped during the plugin uninstallation.
 === db/events.php ===
 Event handlers (subscriptions) are defined here. It lists all the events that your plugin want to observe and be notified about.
 * [[Events API]]
 === db/messages.php ===
 Allow to declare your plugin as the messaging provider.
 * [[Message API]]
 === db/services.php ===
 External functions and web services provided by your plugin are described here.
 * [[Adding a web service to a plugin]]
 * [[Web services API]]
 * [[External functions API]]
+=== db/renamedclasses.php ===
+Details of classes that have been renamed to fit in with autoloading. See [https://moodle.org/mod/forum/discuss.php?d=262403 forum discussion] for details.
+Please note that the new classname ''must'' exist and should not be prefixed with a leading backslash.<syntaxhighlight lang="php">
+<?php
-=== db/renamedclasses.php ===
+defined('MOODLE_INTERNAL') || die;
+$renamedclasses = [
+    // Format:
+    'old_class_name' => 'fully_qualified\\new\\name',
+    // Examples:
+    'assign_header' => 'mod_assign\\output\\header',
+    '\assign_header' => 'mod_assign\\output\\header',
+    '\assign' => 'mod_assign\\assignment',
-Details of classes that have been renamed to fit in with autoloading. See [https://moodle.org/mod/forum/discuss.php?d=262403 forum discussion] for details
+    // Bad:
+    'assign_header' => '\\mod_assign\\output\\header',
+];
+</syntaxhighlight>
 === classes/ ===
 * [[Automatic class loading]]
 * [[Coding style#Namespaces]]
 === cli/ ===
 It is a convention in the Moodle code that all [[CLI scripts]] are put into the <tt>cli/</tt> folder inside the plugin directory. Make sure all these files declare themselves as CLI scripts properly (the constant must be defined prior to loading the config.php):
+<syntaxhighlight lang="php">
-<code php>
 define('CLI_SCRIPT', true);
 require(__DIR__.'/../../../config.php');
 require_once($CFG->libdir.'/clilib.php');
-</code>
+</syntaxhighlight>
 === settings.php ===
 Describes the administration configuration for your plugin.
 The setting names are supposed to be <tt>plugintype_pluginname/settingname</tt> (note the slash) and not plugintype_pluginname_settingname or even just settingname. This makes them to be stored in the <tt>config_plugins</tt> table without polluting the global <tt>$CFG</tt> object.
 * [[Admin settings]]
 === amd/ ===
 Plugin's Javascript modules written using AMD or ES6 format. (AMD, supported since Moodle 2.9, ES6 since Moodle 3.8).
 '''Note: ''' Since Moodle 3.9, all files must be in an ES6 format for acceptance into core.
 * [[Javascript Modules]]
 === yui/ ===
 Plugin's YUI modules (recommended way to include Javascript in Moodle 2.8 and older).
 '''Note: ''' The inclusion of new YUI modules will not be accepted to Moodle core from Moodle 3.8 onwards with the exception of Atto Editor plugins.
 * [[YUI/Modules]]
 * [[YUI]]
 === jquery/ ===
 Plugin's jQuery modules (Moodle 2.8 and older)
 '''Note: ''' The inclusion of jQuery modules will not be accepted to Moodle core from Moodle 2.9 onwards.
 * [[jQuery pre2.9]]
 === styles.css ===
 The plugin's CSS are stored here.
 * [[Plugin contribution checklist#CSS styles]]
 * [[CSS Coding Style]]
 === pix/icon.svg ===
 The plugin's icon. [[Activity modules]] should provide 24 x 24 px colour icons. All other plugin files should be represented by 16 x 16 px monochrome icon. There should be a fallback <tt>pix/icon.png</tt> version of the icon for legacy browsers.
 * [[Moodle icons]] provides icons design guidelines
 === thirdpartylibs.xml ===
 The file should list all 3rd party libraries bundled with a plugin.
+<syntaxhighlight lang="xml">
-<code xml>
 <?xml version="1.0"?>
 <libraries>
@@ Line 168: / Line 126: @@
      </library>
 </libraries>
-</code>
+</syntaxhighlight>
 The <tt>location</tt> is a path to the library directory or file, relative to the plugin's root directory. Please note that <tt>license</tt> must be always [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses compatible with the GNU GPLv3].
@@ Line 175: / Line 132: @@
 More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries
 === readme_moodle.txt  ===
 The file should contain detailed instructions on how to import 3rd party libraries into Moodle. This should list:
 * Download URLs
 * Build instructions
 More information about 3rd party libraries can be found at: https://docs.moodle.org/dev/Third_Party_Libraries
 === environment.xml ===
 Plugin can declare its additional environment requirements via this file - such as compulsory presence of some otherwise optional PHP extension. See [[Environment checking#Configuration file overview]] for details of the syntax.
+<syntaxhighlight lang="xml">
-<code xml>
 <?xml version="1.0" encoding="UTF-8" ?>
 <COMPATIBILITY_MATRIX>
@@ Line 199: / Line 149: @@
    </PLUGIN>
 </COMPATIBILITY_MATRIX>
-</code>
+</syntaxhighlight>
 === README ===
 The file <tt>README.md</tt> or <tt>README.txt</tt> should contain useful information about the plugin. Ideally, it should act as an offline version of all the informations that are available at the plugin's page in the [[Plugins directory]].
 === CHANGES ===
 If the file <tt>CHANGES.md</tt> (or <tt>CHANGES.txt</tt>, <tt>CHANGES.html</tt> or just <tt>CHANGES</tt> alternatively) is found when uploading a new plugin version into the [[Plugins directory]], then the contents of this file is used to pre-fill the release notes field for the new version.
 == See also ==
 * [[Moodle architecture]] - general overview of Moodle code architecture
 * [[Plugin types]] - list of all supported plugin types