Local plugins

Revision as of 19:10, 19 May 2010 by Petr Škoda (škoďák) (talk | contribs) (Custom /local/ plugins)

Jump to: navigation, search
Local customisations
Project state In progress
Tracker issue MDL-17376, MDL-16438
Discussion http://moodle.org/mod/forum/discuss.php?d=126017
Assignee Petr Škoda (škoďák), original proposal and implementation in 1.9 by Penny Leach

Moodle 2.0


The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

Custom /local/ plugins

Standard plugin features:

  • /local/xxx/db/version.php - version of script (must be incremented after changes)
  • /local/xxx/db/install.xml - executed during install (new version.php found)
  • /local/xxx/db/install.php - executed right after install.xml
  • /local/xxx/db/upgrade.php - executed after version.php change
  • /local/xxx/db/access.php - definition of capabilities
  • /local/xxx/db/events.php - event handlers and subscripts
  • /local/xxx/db/messages.php - messaging registration
  • /local/xxx/db/external.php - web services and external functions descriptions
  • /local/xxx/lang/en/local_pluginname.php - language file

The xxx is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.


List of differences from normal plugins:

  • always executed last during install/upgrade - guaranteed by order of plugins in
    get_plugin_types()
  • are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
  • can add admin settings to any settings page - loaded last when constructing admin tree
  • do not need to have any UI - other plugins are usually visible somewhere
  • some extra hooks (not implemented yet)

Other /local/ customisation files

Customised site defaults

2.0 pre-upgrade script

Customisations outside of /local/ directory

Forced settings

Local language customisations

Custom script injection

Direct code modifications

This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

Direct database modifications

Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

Local customisations in previous versions

Previous versions include only partial support for customisations in /local/ directory.

List of local customisations in 1.9.x:

  • /local/cron.php - custom cron jobs
  • /local/settings.php - custom admin settings
  • /local/db/upgrade.php - general modifications
  • /local/lang/* - custom strings
  • /local/lib.php - local_delete_course()


Migration from old 1.9.x /local/:

  • local/*
    needs to be copied to new directory
  • local/xxxx/db/install.php
    is intended for first installation, originally everything was in upgrade.php
  • events are used instead of hooks
  • upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

See also