MoodleDocs - User contributions [en]

Setting up PhpStorm

2015-08-26T03:12:59Z

Skodak: /* OS X */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===

Do not install Java manually, download a PhpStorm package with bundled java instead.

==General settings==

* Disable missing @throws tag warning in "Preferences / Project Settings / Inspections / PHP / PHPDoc"
* Strip trailing whitespace from "Modified Lines" in "Preferences / IDE Settings / Editor"
* Show line numbers in "Preferences / IDE Settings / Editor / Appearance"

==Bug tracker integration==

* Add tracker linking in "Preferences / Version control / Issue Navigation"
* Set Issue ID to "MDL-\d+" and Issue link to "https://tracker.moodle.org/browse/$0"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Project Settings / Code Style / PHP" - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to Unix in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Moodle code checker==
TODO

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

Server clustering improvements proposal

2015-07-21T02:07:26Z

Skodak: /* $CFG->tempdir */

{{Moodle 2.6}}

Author: [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 4 July 2013 (WST) and others

MDL-40979 was raised to group together this issues that are raised out of this document and the discussion. All issues should be linked to that EPIC.

==Cluster configuration requirements==

# Cluster node clocks must be synchronised with difference <1s.
# Database setup must be ACID compliant.
# $CFG->dataroot must be a shared directory.
# $CFG->cachedir must be a shared directory.

Note that these last two often cause confusion. These directories must be shared because Moodle code relies on that, all cluster nodes must see the same data there. Cluster headaches do occur when there is a lot of data in here, so our aim is to REDUCE dependence on shared caches as much as possible, technically it is not possible to have only local caches.

==config.php settings==
Each node in cluster may use local set of php files including config.php, these may be synchronised via git for example, rsync, etc.

===$CFG->wwwroot===
It must be the same on all nodes, it must be the public facing URL. It cannot be dynamic.

===$CFG->sslproxy===
Enable if you have https:// wwwroot but the SSL is not done by Apache.

Do not forget to enable ''Secure cookies only'' to make your site really secure, without it cookie stealing is still trivial.

===$CFG->reverseproxy===
Enable if your nodes are accessed via different URL. Please note that it is not compatible with $CFG->loginhttps.

===$CFG->dirroot===
It is strongly recommended that $CFG->dirroot (which is automatically set via realpath(config.php)) contains the same path on all nodes. It does not need to point to the same shared directory though. The reason is that some some low level code may use the dirroot value for cache invalidation.

The simplest solution is to have the same directory structure on each cluster node and synchronise these during each upgrade.

The dirroot should be always read only for apache process because otherwise built in add-on installation and plugin uninstallation would get the nodes out of sync.

===$CFG->dataroot===

This '''MUST''' be a shared directory where each cluster node is accessing the files directly. It must be very reliable, administrators cannot manipulate files directly there.

Locking support is not required, if any code tries to use file locks in dataroot outside of cachedir or muc directory it is a bug.

===$CFG->tempdir===

'''Requirement: $CFG->tempdir is a directory that must be shared by all cluster nodes.'''

The contents of this directory may be deleted if there is no pending HTTP request.

In 2.9 and later use new request directory instead where possible.

===$CFG->cachedir===

'''Requirement: $CFG->cachedir is a directory shared by all cluster nodes.'''

Cache invalidation is done by deleting or overriding of existing files, this needs to be automatically replicated to all cluster nodes, otherwise the cache may return stale or invalid data which often leads to fatal errors or data loss.

The existing documentation clearly states that this directory must be shared, all existing code including add-ons may expect this, it is therefore not possible to change this requirement without breaking backwards compatibility.

Please note that MUC caches have similar problem, the current design expects that each node is contacting the same caches. It should be possible to create new MUC backends that do not require shared cache backends in a way similar to the proposed $CFG->localcachedir .

You can safely purge cachedir when restarting the whole cluster, you may get some notices or temporary errors if you purge this directory while other requests are active.

Netspot admins came up with a hypothesis that "cachedir does not have to be shared", it is easy to disapprove it - we need to find a single case where the sharing is required. Let's look at the caching of data from config table in $CFG global variable. If one node modifies CFG value others would not be notified about the change and would continue using stale value. Workaround seems to be to create a new revision number that is incremented after any change in $CFG and share it with all nodes. The question is where to put it so that it is shared by all nodes? Storing it in database would require one extra read on each page and one extra write on each update, that is not acceptable. We cannot put the revision into a shared filesystem because we would not have it. We cannot rely on presence of memcache or any shared data storage in default installation either. In most other cases we store the revision flags in CFG itself, it is clearly not possible in this case because it would not be shared by nodes. Somebody said "but it works without sharing for all our clients for at least a year" - that does not prove anything, you would have to make sure it works also for everybody else with all add-ons, custom modifications and minimal number of PHP extensions required by Moodle.

In any case cachedir is shared by definition since the beginning of its existence, it is a fact that developers writing code may depend on. If you do not like it then use local cache dir.

== New $CFG->localcachedir==

The difference from normal $CFG->cachedir is that the directory does not have to be shared by all cluster nodes, the files stored in $CFG->localcachedir MUST NOT change! Default directory is "$CFG->dataroot/localcache".

All files there must use unique revision numbers or hashes because the cached data cannot be invalidated by other mechanism - it will support only adding of new files, but no file deletes or overrides. The $CFG->localcachedir will be growing over time, all local cache files will be deleted during purge_all_caches() (automatically during upgrades).

When using hashes please make sure the number of files in one directory is kept to some reasonable number because some filesystems might have problems with large number of files in one directory.

Note that some caches cannot be easily moved to localcachedir because you need a reliable revision number here, but sometimes it is either not possible or very slow because you need to store the revision number somewhere and you need to bump up the revision number after any change and you would need to store it in database. Caching is not free, each usage must be carefully evaluated.

Design requirements:
* Everything must be automatic without extra administrative overhead.
* purge_all_caches() on any node triggers local cache purging on all other nodes before adding any new files there.
* Performance on standalone servers must not be worse.

Usage restrictions:
* No file deletes
* No file modifications
* No file overwriting
* Soft limit on maximum number of files in one directory (few thousands)

Benefits:
* Clustered servers may use fast local filesystem such as tempfs.
* No opcache cache invalidation problems if php files included from localcachedir (because the files must not change).

Candidates for migration from $CFG->cachedir:
* JS cache MDL-40546
* Theme caches MDL-40563
* HTMLPurifier cache MDL-41017

''Implemented in Moodle 2.6, see MDL-40545.''

==Component cache==

Class core_component is using a $CFG->cachedir/core_component.php cache that contains a complete list of all plugins and all classes present in $CFG->dirroot. The implementation must be as fast as possible and the results must be extremely reliable.

The cache is automatically invalidated on admin/index.php page and during installation and every upgrade. It is also cleared during purge_all_caches(), but that is only a side effect of storing it in cachedir and it is not required.

core_component class cannot depend on database, MUC or any core libraries - that is the reason why there cannot be any revision flag, there is nowhere to store it, the sha1() of that file content would be the revision. But we would have to go through all plugin directories to find out if it was changed or what revision to use. There are only two options - either we store this file in shared cache or admin invalidates this cache manually, the second option it clearly not acceptable for standard installations.

===Alternative component cache location===

This is useful for clustered installations only. Typically the $CFG->alternative_component_cache = '/local/cache/dir/core_component.php' would point to local node cache directory. Before upgrade the administrator would have to manually execute following on each node:

<code>
$ php admin/cli/alternative_component_cache.php --rebuild
</code>

Alternatively you could put the cache file directly into dirroot and distribute it together with new PHP source files. Yet another possibility would be to purge all local caches on all nodes before upgrade or simply change the script name in config.php on all nodes before upgrade.

''Implemented in Moodle 2.6, see MDL-40475.''

==MUC and clustering==

At present administrators are free to create new stores and assign them to existing definitions of each cache. Unfortunately the documentation or admin UI does not mention that by default all those definitions require cache stores to be shared by all cluster nodes! Some cache keys may include revision numbers and all settings which makes them compatible with local caches, we need to document it somewhere.

I would like to propose a new flag in cache definition '''localcache''' which would indicate that it is safe to use local cache stores on cluster nodes. For now we can at least document it in db/caches.php as inline comments. This information should be clearly visible on the cache store/definition settings page. Maybe we could add setting to cache stores which indicates if it is a shared or local cache. The only potential problem is that it might confuse admins that know little about clustering or cache invalidation.

In theory the installation could create two file stores by default - one using current $CFG->cachedir and second using $CFG->localcachedir and assign them to definitions based on localcache flag. This could help new admins when setting up clusters, all they would have to do would be to move localcachedir to cluster node ram disks.

Note that MODE_REQUEST are local by definition and MODE_SESSION are always shared (because session is shared), this means we need to consider only MODE_APPLICATION definitions here.

List of caches/definitions that are compatible with local caching on cluster nodes:
* core htmlpurifier - MDL-41017
* core string - MDL-41019
* core langmenucache - MDL-41019
*

==Theme caching==

''All large installs and clusters should use transparent proxies (such as Cloudflare or custom nginx).''

Small installs without transparent caches (or when in designer mode) depend on performance of theme serving scripts (theme/image.php, theme/styles.php, etc.).

The serving scripts receive revision number in URL, this solves the problem with cache invalidation. We are not using MUC there intentionally because we are not in already open HTTP request with database connection and all standard libraries already loaded, the data there must be served quickly with as little memory and CPU cycles as possible.

The standard theme caches may be stored in local node caches, we could store the theme caches in $CFG->localcachedir/theme/ directory.

Theme designer mode is not using any revisions. For performance reasons we must use some cache, the only option seems to be the standard shared $CFG->cachedir/theme/. Using localcachedir is not an option here, we might try to improve the general performance here and if possible skip all caching in theme designer mode.

''Theme caching was improved in 2.6, it is using localcachedir, see MDL-40563.''

==Javascript caching==

We used JS caching in cachedir for performance reasons because we were doing on-the-fly JS compression. Ideally we should switch to build system for all JS files and store the minimised files along the source files in git and just add proper headers in lib/javascript.php script.

''JavaScript caching was improved in 2.6, it is using localcachedir, see MDL-40546.''

==Language installation and customisations==

Each string is constructed from the following sources:
# en pack in plugin/core - always distributed with plugin
# current language pack, including all its parents - downloaded into $CFG->langotherroot (usually $CFG->dataroot/lang)
# local string tweaks - created with tool_customlang, stored in $CFG->langlocalroot in directories with "_local" suffix (usually $CFG->dataroot/lang)

We can use existing $CFG->langrev in cache keys to add support for local lang caches on cluster nodes.

Please note that language packs and local modifications are PHP files, you need to verify file timestamps or blacklist these locations in OP code caches on cluster nodes.

There is another cache for available translations which is stored in $CFG->langmenucachefile, we can move this to MUC and allow local node caches too.

''Lang caching is improved in 2.6, see MDL-41019.''

==PHP accelerators==

Potential problems:
* file time stamps must be verified in Moodle 2.5 and bellow

===opcache extension===

Standard ''opcache'' extension is strongly recommended for Moodle 2.6 forward, it is the only solution officially supported by PHP developers. Starting with Moodle 2.6 we should recommend the opcache extension during environment test. All other PHP accelerators should be actively discourage (warning on environment page).

Please note that HQ developers are not required to test current stable branches with any PHP accelerators.

The goal is to use opcaching without checking of file modification times - problem here are dynamically generated PHP files that are stored in dataroot (component cache, lang packs, local lang modifications, muc config, etc.), we need to invalidate the op code cache explicitly.

''OPcache extension is fully supported in Moodle 2.6, see MDL-40415.''

==Browser sessions==

User session data should be stored in some reliable shared storage, all cluster nodes need to operate with the same session data, the data must not be disappearing randomly.

All sessions drivers should be updating the list of active sessions in the session table, the serialised session data can be stored somewhere else.

Moodle session drivers need to support some special features:
* Session timeout is controlled from Moodle code - it is required for reliable SSO implementations.
* We need to be able to query list of all sessions belonging to one user - this allows us to logout deleted users (for example spammers).
* Locking is strongly recommended because race conditions may create hard to diagnose problems - users need to logout/login to recover from these problems.
* Sometimes the structure of session data changes and then upgrade requires logout of all active users.
* Some add-ons/patches use the information from sessions table to implement limits for concurrent user logins.

By default new installations are using a databases session driver with locking support. There is a legacy file based session driver for sites that cannot use db sessions, but it does not support any advanced features above and is therefore not recommended.

PHP lacks a reliable cross-platform locking support, this is one if major problems when implementing new session drivers. Without locking the changes in user session may be lost resulting in hard to diagnose problems. Another problem when adding new session driver is that the sessions table needs to be updated at least once per minute.

* MDL-31501 is the ticket for implementing a workable memcached session storage backend.
* MDL-25500 is the ticket to implement a general locking mechanism.

''Not implemented yet.''

==File pool==

At present there is a filedir in dataroot where we store all contents of files in Moodle. Theoretically the code could be abstracted to allow storage of file contents in non-filesystem storage.

The default location is $CFG->dataroot/filedir, alterantive value can be specified in $CFG->filedir setting. $CFG->filedir does not require locking, it may be outside of $CFG->dataroot. The file system/sharing may use very aggressive caching techniques because the files never change, the node needs to contact the master when writing or on cache miss.

The original idea was to have a setting for preventing of file removals from the $CFG->filedir directory, this would allow you to put files from multiple installations into just one giant file pool that could be replicated to all nodes - files would be only added there and never deleted automatically. The only potential problem is size of this huge dir and there would have to be a special new tool that exports used files from one site to another that is not using the shared file pool. The setting was supposed to be in file_storage::deleted_file_cleanup() method (one if that simply exits method).

MDL-40528 contains a refactoring of trashdir operations that could help anybody who decides to reimplement the fole_storage class. The sample backup recovery class might be also user for simple local filedir cache on cluster nodes.

==Installation procedure==

1. Build a 1 node cluster
- NFS backing storage
- Configuration parameters like there are lots of nodes
- Database setup on own host and such.
- Build load balancer configuration.
- Run moodle install cli
- Add appropriate configuration items to get the system working behind load balancer
2. Add more nodes to the cluster by replicating the first node.

==Upgrade procedure==

===Sample estimation===
# tweak load balancer to redirect all users to some static non-moodle page
# shutdown all nodes except one
# optionally enable CLI maintenance mode
# upload new PHP files to all nodes
# rebuild component cache if alternative read only location used
# upgrade the node from CLI
# disable CLI maintenance mode
# start other nodes (this guarantees localcachedir purging)
# enable normal operation

===Large in-house NFS backend VM upgrade===
CLI Maintenance mode may be useful, but either way, you we stop all web nodes and also ensure that the current cron run has finished, otherwise you can get into all sort of strife. Trying to do an upgrade during the forum digest time or stats run is not possible. Both can run for >1 hour.

Opcode resets are a problem when moving from CLI to apache for fcgi. As I understand it, each has its own opcache location and that needs to be managed properly. Hence the just shutdown the web nodes to force resets.

1. Disable all users except administrator who is upgrading. (This is done via IP at our load balancer)
2. Stop apache on all nodes
3. Stop cron from running and ensure it's finished.

We then ignore the fact we are in a cluster for a few instructions and operate on one node.

3.1 Backup/snapshot database and dataroot

4. Upload new php files to 'master' node.
5. Upgrade 'master' node. admin/cli/upgrade.php
6. Start up 'master' node apache, and test with admin login.
7. If all successful, copy code to all other nodes
8. Turn on other nodes.
9. Browse around a bit to ensure you have warmed the opcache (cold cache can cause floods with 500+ users logging in within 10 seconds of go-live)
10. Turn the system back on for all users.

==Database clustering==

Anything ACID compliant should be ok. For example even-odd master-master MySQL is not ok.

TODO: add descriptions of ACID compliant DB cluster setups

==More information==

* [http://thamblings.blogspot.cz/2013/07/deploying-moodle-continued.html Deploying Moodle]
* [https://docs.moodle.org/25/en/Server_cluster Server cluster (user docs)]

Server clustering improvements proposal

2015-07-21T02:06:58Z

Skodak: /* Sample estimation */

{{Moodle 2.6}}

Author: [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 4 July 2013 (WST) and others

MDL-40979 was raised to group together this issues that are raised out of this document and the discussion. All issues should be linked to that EPIC.

==Cluster configuration requirements==

# Cluster node clocks must be synchronised with difference <1s.
# Database setup must be ACID compliant.
# $CFG->dataroot must be a shared directory.
# $CFG->cachedir must be a shared directory.

Note that these last two often cause confusion. These directories must be shared because Moodle code relies on that, all cluster nodes must see the same data there. Cluster headaches do occur when there is a lot of data in here, so our aim is to REDUCE dependence on shared caches as much as possible, technically it is not possible to have only local caches.

==config.php settings==
Each node in cluster may use local set of php files including config.php, these may be synchronised via git for example, rsync, etc.

===$CFG->wwwroot===
It must be the same on all nodes, it must be the public facing URL. It cannot be dynamic.

===$CFG->sslproxy===
Enable if you have https:// wwwroot but the SSL is not done by Apache.

Do not forget to enable ''Secure cookies only'' to make your site really secure, without it cookie stealing is still trivial.

===$CFG->reverseproxy===
Enable if your nodes are accessed via different URL. Please note that it is not compatible with $CFG->loginhttps.

===$CFG->dirroot===
It is strongly recommended that $CFG->dirroot (which is automatically set via realpath(config.php)) contains the same path on all nodes. It does not need to point to the same shared directory though. The reason is that some some low level code may use the dirroot value for cache invalidation.

The simplest solution is to have the same directory structure on each cluster node and synchronise these during each upgrade.

The dirroot should be always read only for apache process because otherwise built in add-on installation and plugin uninstallation would get the nodes out of sync.

===$CFG->dataroot===

This '''MUST''' be a shared directory where each cluster node is accessing the files directly. It must be very reliable, administrators cannot manipulate files directly there.

Locking support is not required, if any code tries to use file locks in dataroot outside of cachedir or muc directory it is a bug.

===$CFG->tempdir===

'''Requirement: $CFG->tempdir is a directory that must be shared by all cluster nodes.'''

The contents of this directory may be deleted if there is no pending HTTP request.

In 2.9 and later user request directory where possible.

===$CFG->cachedir===

'''Requirement: $CFG->cachedir is a directory shared by all cluster nodes.'''

Cache invalidation is done by deleting or overriding of existing files, this needs to be automatically replicated to all cluster nodes, otherwise the cache may return stale or invalid data which often leads to fatal errors or data loss.

The existing documentation clearly states that this directory must be shared, all existing code including add-ons may expect this, it is therefore not possible to change this requirement without breaking backwards compatibility.

Please note that MUC caches have similar problem, the current design expects that each node is contacting the same caches. It should be possible to create new MUC backends that do not require shared cache backends in a way similar to the proposed $CFG->localcachedir .

You can safely purge cachedir when restarting the whole cluster, you may get some notices or temporary errors if you purge this directory while other requests are active.

Netspot admins came up with a hypothesis that "cachedir does not have to be shared", it is easy to disapprove it - we need to find a single case where the sharing is required. Let's look at the caching of data from config table in $CFG global variable. If one node modifies CFG value others would not be notified about the change and would continue using stale value. Workaround seems to be to create a new revision number that is incremented after any change in $CFG and share it with all nodes. The question is where to put it so that it is shared by all nodes? Storing it in database would require one extra read on each page and one extra write on each update, that is not acceptable. We cannot put the revision into a shared filesystem because we would not have it. We cannot rely on presence of memcache or any shared data storage in default installation either. In most other cases we store the revision flags in CFG itself, it is clearly not possible in this case because it would not be shared by nodes. Somebody said "but it works without sharing for all our clients for at least a year" - that does not prove anything, you would have to make sure it works also for everybody else with all add-ons, custom modifications and minimal number of PHP extensions required by Moodle.

In any case cachedir is shared by definition since the beginning of its existence, it is a fact that developers writing code may depend on. If you do not like it then use local cache dir.

== New $CFG->localcachedir==

The difference from normal $CFG->cachedir is that the directory does not have to be shared by all cluster nodes, the files stored in $CFG->localcachedir MUST NOT change! Default directory is "$CFG->dataroot/localcache".

All files there must use unique revision numbers or hashes because the cached data cannot be invalidated by other mechanism - it will support only adding of new files, but no file deletes or overrides. The $CFG->localcachedir will be growing over time, all local cache files will be deleted during purge_all_caches() (automatically during upgrades).

When using hashes please make sure the number of files in one directory is kept to some reasonable number because some filesystems might have problems with large number of files in one directory.

Note that some caches cannot be easily moved to localcachedir because you need a reliable revision number here, but sometimes it is either not possible or very slow because you need to store the revision number somewhere and you need to bump up the revision number after any change and you would need to store it in database. Caching is not free, each usage must be carefully evaluated.

Design requirements:
* Everything must be automatic without extra administrative overhead.
* purge_all_caches() on any node triggers local cache purging on all other nodes before adding any new files there.
* Performance on standalone servers must not be worse.

Usage restrictions:
* No file deletes
* No file modifications
* No file overwriting
* Soft limit on maximum number of files in one directory (few thousands)

Benefits:
* Clustered servers may use fast local filesystem such as tempfs.
* No opcache cache invalidation problems if php files included from localcachedir (because the files must not change).

Candidates for migration from $CFG->cachedir:
* JS cache MDL-40546
* Theme caches MDL-40563
* HTMLPurifier cache MDL-41017

''Implemented in Moodle 2.6, see MDL-40545.''

==Component cache==

Class core_component is using a $CFG->cachedir/core_component.php cache that contains a complete list of all plugins and all classes present in $CFG->dirroot. The implementation must be as fast as possible and the results must be extremely reliable.

The cache is automatically invalidated on admin/index.php page and during installation and every upgrade. It is also cleared during purge_all_caches(), but that is only a side effect of storing it in cachedir and it is not required.

core_component class cannot depend on database, MUC or any core libraries - that is the reason why there cannot be any revision flag, there is nowhere to store it, the sha1() of that file content would be the revision. But we would have to go through all plugin directories to find out if it was changed or what revision to use. There are only two options - either we store this file in shared cache or admin invalidates this cache manually, the second option it clearly not acceptable for standard installations.

===Alternative component cache location===

This is useful for clustered installations only. Typically the $CFG->alternative_component_cache = '/local/cache/dir/core_component.php' would point to local node cache directory. Before upgrade the administrator would have to manually execute following on each node:

<code>
$ php admin/cli/alternative_component_cache.php --rebuild
</code>

Alternatively you could put the cache file directly into dirroot and distribute it together with new PHP source files. Yet another possibility would be to purge all local caches on all nodes before upgrade or simply change the script name in config.php on all nodes before upgrade.

''Implemented in Moodle 2.6, see MDL-40475.''

==MUC and clustering==

At present administrators are free to create new stores and assign them to existing definitions of each cache. Unfortunately the documentation or admin UI does not mention that by default all those definitions require cache stores to be shared by all cluster nodes! Some cache keys may include revision numbers and all settings which makes them compatible with local caches, we need to document it somewhere.

I would like to propose a new flag in cache definition '''localcache''' which would indicate that it is safe to use local cache stores on cluster nodes. For now we can at least document it in db/caches.php as inline comments. This information should be clearly visible on the cache store/definition settings page. Maybe we could add setting to cache stores which indicates if it is a shared or local cache. The only potential problem is that it might confuse admins that know little about clustering or cache invalidation.

In theory the installation could create two file stores by default - one using current $CFG->cachedir and second using $CFG->localcachedir and assign them to definitions based on localcache flag. This could help new admins when setting up clusters, all they would have to do would be to move localcachedir to cluster node ram disks.

Note that MODE_REQUEST are local by definition and MODE_SESSION are always shared (because session is shared), this means we need to consider only MODE_APPLICATION definitions here.

List of caches/definitions that are compatible with local caching on cluster nodes:
* core htmlpurifier - MDL-41017
* core string - MDL-41019
* core langmenucache - MDL-41019
*

==Theme caching==

''All large installs and clusters should use transparent proxies (such as Cloudflare or custom nginx).''

Small installs without transparent caches (or when in designer mode) depend on performance of theme serving scripts (theme/image.php, theme/styles.php, etc.).

The serving scripts receive revision number in URL, this solves the problem with cache invalidation. We are not using MUC there intentionally because we are not in already open HTTP request with database connection and all standard libraries already loaded, the data there must be served quickly with as little memory and CPU cycles as possible.

The standard theme caches may be stored in local node caches, we could store the theme caches in $CFG->localcachedir/theme/ directory.

Theme designer mode is not using any revisions. For performance reasons we must use some cache, the only option seems to be the standard shared $CFG->cachedir/theme/. Using localcachedir is not an option here, we might try to improve the general performance here and if possible skip all caching in theme designer mode.

''Theme caching was improved in 2.6, it is using localcachedir, see MDL-40563.''

==Javascript caching==

We used JS caching in cachedir for performance reasons because we were doing on-the-fly JS compression. Ideally we should switch to build system for all JS files and store the minimised files along the source files in git and just add proper headers in lib/javascript.php script.

''JavaScript caching was improved in 2.6, it is using localcachedir, see MDL-40546.''

==Language installation and customisations==

Each string is constructed from the following sources:
# en pack in plugin/core - always distributed with plugin
# current language pack, including all its parents - downloaded into $CFG->langotherroot (usually $CFG->dataroot/lang)
# local string tweaks - created with tool_customlang, stored in $CFG->langlocalroot in directories with "_local" suffix (usually $CFG->dataroot/lang)

We can use existing $CFG->langrev in cache keys to add support for local lang caches on cluster nodes.

Please note that language packs and local modifications are PHP files, you need to verify file timestamps or blacklist these locations in OP code caches on cluster nodes.

There is another cache for available translations which is stored in $CFG->langmenucachefile, we can move this to MUC and allow local node caches too.

''Lang caching is improved in 2.6, see MDL-41019.''

==PHP accelerators==

Potential problems:
* file time stamps must be verified in Moodle 2.5 and bellow

===opcache extension===

Standard ''opcache'' extension is strongly recommended for Moodle 2.6 forward, it is the only solution officially supported by PHP developers. Starting with Moodle 2.6 we should recommend the opcache extension during environment test. All other PHP accelerators should be actively discourage (warning on environment page).

Please note that HQ developers are not required to test current stable branches with any PHP accelerators.

The goal is to use opcaching without checking of file modification times - problem here are dynamically generated PHP files that are stored in dataroot (component cache, lang packs, local lang modifications, muc config, etc.), we need to invalidate the op code cache explicitly.

''OPcache extension is fully supported in Moodle 2.6, see MDL-40415.''

==Browser sessions==

User session data should be stored in some reliable shared storage, all cluster nodes need to operate with the same session data, the data must not be disappearing randomly.

All sessions drivers should be updating the list of active sessions in the session table, the serialised session data can be stored somewhere else.

Moodle session drivers need to support some special features:
* Session timeout is controlled from Moodle code - it is required for reliable SSO implementations.
* We need to be able to query list of all sessions belonging to one user - this allows us to logout deleted users (for example spammers).
* Locking is strongly recommended because race conditions may create hard to diagnose problems - users need to logout/login to recover from these problems.
* Sometimes the structure of session data changes and then upgrade requires logout of all active users.
* Some add-ons/patches use the information from sessions table to implement limits for concurrent user logins.

By default new installations are using a databases session driver with locking support. There is a legacy file based session driver for sites that cannot use db sessions, but it does not support any advanced features above and is therefore not recommended.

PHP lacks a reliable cross-platform locking support, this is one if major problems when implementing new session drivers. Without locking the changes in user session may be lost resulting in hard to diagnose problems. Another problem when adding new session driver is that the sessions table needs to be updated at least once per minute.

* MDL-31501 is the ticket for implementing a workable memcached session storage backend.
* MDL-25500 is the ticket to implement a general locking mechanism.

''Not implemented yet.''

==File pool==

At present there is a filedir in dataroot where we store all contents of files in Moodle. Theoretically the code could be abstracted to allow storage of file contents in non-filesystem storage.

The default location is $CFG->dataroot/filedir, alterantive value can be specified in $CFG->filedir setting. $CFG->filedir does not require locking, it may be outside of $CFG->dataroot. The file system/sharing may use very aggressive caching techniques because the files never change, the node needs to contact the master when writing or on cache miss.

The original idea was to have a setting for preventing of file removals from the $CFG->filedir directory, this would allow you to put files from multiple installations into just one giant file pool that could be replicated to all nodes - files would be only added there and never deleted automatically. The only potential problem is size of this huge dir and there would have to be a special new tool that exports used files from one site to another that is not using the shared file pool. The setting was supposed to be in file_storage::deleted_file_cleanup() method (one if that simply exits method).

MDL-40528 contains a refactoring of trashdir operations that could help anybody who decides to reimplement the fole_storage class. The sample backup recovery class might be also user for simple local filedir cache on cluster nodes.

==Installation procedure==

1. Build a 1 node cluster
- NFS backing storage
- Configuration parameters like there are lots of nodes
- Database setup on own host and such.
- Build load balancer configuration.
- Run moodle install cli
- Add appropriate configuration items to get the system working behind load balancer
2. Add more nodes to the cluster by replicating the first node.

==Upgrade procedure==

===Sample estimation===
# tweak load balancer to redirect all users to some static non-moodle page
# shutdown all nodes except one
# optionally enable CLI maintenance mode
# upload new PHP files to all nodes
# rebuild component cache if alternative read only location used
# upgrade the node from CLI
# disable CLI maintenance mode
# start other nodes (this guarantees localcachedir purging)
# enable normal operation

===Large in-house NFS backend VM upgrade===
CLI Maintenance mode may be useful, but either way, you we stop all web nodes and also ensure that the current cron run has finished, otherwise you can get into all sort of strife. Trying to do an upgrade during the forum digest time or stats run is not possible. Both can run for >1 hour.

Opcode resets are a problem when moving from CLI to apache for fcgi. As I understand it, each has its own opcache location and that needs to be managed properly. Hence the just shutdown the web nodes to force resets.

1. Disable all users except administrator who is upgrading. (This is done via IP at our load balancer)
2. Stop apache on all nodes
3. Stop cron from running and ensure it's finished.

We then ignore the fact we are in a cluster for a few instructions and operate on one node.

3.1 Backup/snapshot database and dataroot

4. Upload new php files to 'master' node.
5. Upgrade 'master' node. admin/cli/upgrade.php
6. Start up 'master' node apache, and test with admin login.
7. If all successful, copy code to all other nodes
8. Turn on other nodes.
9. Browse around a bit to ensure you have warmed the opcache (cold cache can cause floods with 500+ users logging in within 10 seconds of go-live)
10. Turn the system back on for all users.

==Database clustering==

Anything ACID compliant should be ok. For example even-odd master-master MySQL is not ok.

TODO: add descriptions of ACID compliant DB cluster setups

==More information==

* [http://thamblings.blogspot.cz/2013/07/deploying-moodle-continued.html Deploying Moodle]
* [https://docs.moodle.org/25/en/Server_cluster Server cluster (user docs)]

Server clustering improvements proposal

2015-07-21T02:06:16Z

Skodak: /* $CFG->tempdir */

{{Moodle 2.6}}

Author: [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 4 July 2013 (WST) and others

MDL-40979 was raised to group together this issues that are raised out of this document and the discussion. All issues should be linked to that EPIC.

==Cluster configuration requirements==

# Cluster node clocks must be synchronised with difference <1s.
# Database setup must be ACID compliant.
# $CFG->dataroot must be a shared directory.
# $CFG->cachedir must be a shared directory.

Note that these last two often cause confusion. These directories must be shared because Moodle code relies on that, all cluster nodes must see the same data there. Cluster headaches do occur when there is a lot of data in here, so our aim is to REDUCE dependence on shared caches as much as possible, technically it is not possible to have only local caches.

==config.php settings==
Each node in cluster may use local set of php files including config.php, these may be synchronised via git for example, rsync, etc.

===$CFG->wwwroot===
It must be the same on all nodes, it must be the public facing URL. It cannot be dynamic.

===$CFG->sslproxy===
Enable if you have https:// wwwroot but the SSL is not done by Apache.

Do not forget to enable ''Secure cookies only'' to make your site really secure, without it cookie stealing is still trivial.

===$CFG->reverseproxy===
Enable if your nodes are accessed via different URL. Please note that it is not compatible with $CFG->loginhttps.

===$CFG->dirroot===
It is strongly recommended that $CFG->dirroot (which is automatically set via realpath(config.php)) contains the same path on all nodes. It does not need to point to the same shared directory though. The reason is that some some low level code may use the dirroot value for cache invalidation.

The simplest solution is to have the same directory structure on each cluster node and synchronise these during each upgrade.

The dirroot should be always read only for apache process because otherwise built in add-on installation and plugin uninstallation would get the nodes out of sync.

===$CFG->dataroot===

This '''MUST''' be a shared directory where each cluster node is accessing the files directly. It must be very reliable, administrators cannot manipulate files directly there.

Locking support is not required, if any code tries to use file locks in dataroot outside of cachedir or muc directory it is a bug.

===$CFG->tempdir===

'''Requirement: $CFG->tempdir is a directory that must be shared by all cluster nodes.'''

The contents of this directory may be deleted if there is no pending HTTP request.

In 2.9 and later user request directory where possible.

===$CFG->cachedir===

'''Requirement: $CFG->cachedir is a directory shared by all cluster nodes.'''

Cache invalidation is done by deleting or overriding of existing files, this needs to be automatically replicated to all cluster nodes, otherwise the cache may return stale or invalid data which often leads to fatal errors or data loss.

The existing documentation clearly states that this directory must be shared, all existing code including add-ons may expect this, it is therefore not possible to change this requirement without breaking backwards compatibility.

Please note that MUC caches have similar problem, the current design expects that each node is contacting the same caches. It should be possible to create new MUC backends that do not require shared cache backends in a way similar to the proposed $CFG->localcachedir .

You can safely purge cachedir when restarting the whole cluster, you may get some notices or temporary errors if you purge this directory while other requests are active.

Netspot admins came up with a hypothesis that "cachedir does not have to be shared", it is easy to disapprove it - we need to find a single case where the sharing is required. Let's look at the caching of data from config table in $CFG global variable. If one node modifies CFG value others would not be notified about the change and would continue using stale value. Workaround seems to be to create a new revision number that is incremented after any change in $CFG and share it with all nodes. The question is where to put it so that it is shared by all nodes? Storing it in database would require one extra read on each page and one extra write on each update, that is not acceptable. We cannot put the revision into a shared filesystem because we would not have it. We cannot rely on presence of memcache or any shared data storage in default installation either. In most other cases we store the revision flags in CFG itself, it is clearly not possible in this case because it would not be shared by nodes. Somebody said "but it works without sharing for all our clients for at least a year" - that does not prove anything, you would have to make sure it works also for everybody else with all add-ons, custom modifications and minimal number of PHP extensions required by Moodle.

In any case cachedir is shared by definition since the beginning of its existence, it is a fact that developers writing code may depend on. If you do not like it then use local cache dir.

== New $CFG->localcachedir==

The difference from normal $CFG->cachedir is that the directory does not have to be shared by all cluster nodes, the files stored in $CFG->localcachedir MUST NOT change! Default directory is "$CFG->dataroot/localcache".

All files there must use unique revision numbers or hashes because the cached data cannot be invalidated by other mechanism - it will support only adding of new files, but no file deletes or overrides. The $CFG->localcachedir will be growing over time, all local cache files will be deleted during purge_all_caches() (automatically during upgrades).

When using hashes please make sure the number of files in one directory is kept to some reasonable number because some filesystems might have problems with large number of files in one directory.

Note that some caches cannot be easily moved to localcachedir because you need a reliable revision number here, but sometimes it is either not possible or very slow because you need to store the revision number somewhere and you need to bump up the revision number after any change and you would need to store it in database. Caching is not free, each usage must be carefully evaluated.

Design requirements:
* Everything must be automatic without extra administrative overhead.
* purge_all_caches() on any node triggers local cache purging on all other nodes before adding any new files there.
* Performance on standalone servers must not be worse.

Usage restrictions:
* No file deletes
* No file modifications
* No file overwriting
* Soft limit on maximum number of files in one directory (few thousands)

Benefits:
* Clustered servers may use fast local filesystem such as tempfs.
* No opcache cache invalidation problems if php files included from localcachedir (because the files must not change).

Candidates for migration from $CFG->cachedir:
* JS cache MDL-40546
* Theme caches MDL-40563
* HTMLPurifier cache MDL-41017

''Implemented in Moodle 2.6, see MDL-40545.''

==Component cache==

Class core_component is using a $CFG->cachedir/core_component.php cache that contains a complete list of all plugins and all classes present in $CFG->dirroot. The implementation must be as fast as possible and the results must be extremely reliable.

The cache is automatically invalidated on admin/index.php page and during installation and every upgrade. It is also cleared during purge_all_caches(), but that is only a side effect of storing it in cachedir and it is not required.

core_component class cannot depend on database, MUC or any core libraries - that is the reason why there cannot be any revision flag, there is nowhere to store it, the sha1() of that file content would be the revision. But we would have to go through all plugin directories to find out if it was changed or what revision to use. There are only two options - either we store this file in shared cache or admin invalidates this cache manually, the second option it clearly not acceptable for standard installations.

===Alternative component cache location===

This is useful for clustered installations only. Typically the $CFG->alternative_component_cache = '/local/cache/dir/core_component.php' would point to local node cache directory. Before upgrade the administrator would have to manually execute following on each node:

<code>
$ php admin/cli/alternative_component_cache.php --rebuild
</code>

Alternatively you could put the cache file directly into dirroot and distribute it together with new PHP source files. Yet another possibility would be to purge all local caches on all nodes before upgrade or simply change the script name in config.php on all nodes before upgrade.

''Implemented in Moodle 2.6, see MDL-40475.''

==MUC and clustering==

At present administrators are free to create new stores and assign them to existing definitions of each cache. Unfortunately the documentation or admin UI does not mention that by default all those definitions require cache stores to be shared by all cluster nodes! Some cache keys may include revision numbers and all settings which makes them compatible with local caches, we need to document it somewhere.

I would like to propose a new flag in cache definition '''localcache''' which would indicate that it is safe to use local cache stores on cluster nodes. For now we can at least document it in db/caches.php as inline comments. This information should be clearly visible on the cache store/definition settings page. Maybe we could add setting to cache stores which indicates if it is a shared or local cache. The only potential problem is that it might confuse admins that know little about clustering or cache invalidation.

In theory the installation could create two file stores by default - one using current $CFG->cachedir and second using $CFG->localcachedir and assign them to definitions based on localcache flag. This could help new admins when setting up clusters, all they would have to do would be to move localcachedir to cluster node ram disks.

Note that MODE_REQUEST are local by definition and MODE_SESSION are always shared (because session is shared), this means we need to consider only MODE_APPLICATION definitions here.

List of caches/definitions that are compatible with local caching on cluster nodes:
* core htmlpurifier - MDL-41017
* core string - MDL-41019
* core langmenucache - MDL-41019
*

==Theme caching==

''All large installs and clusters should use transparent proxies (such as Cloudflare or custom nginx).''

Small installs without transparent caches (or when in designer mode) depend on performance of theme serving scripts (theme/image.php, theme/styles.php, etc.).

The serving scripts receive revision number in URL, this solves the problem with cache invalidation. We are not using MUC there intentionally because we are not in already open HTTP request with database connection and all standard libraries already loaded, the data there must be served quickly with as little memory and CPU cycles as possible.

The standard theme caches may be stored in local node caches, we could store the theme caches in $CFG->localcachedir/theme/ directory.

Theme designer mode is not using any revisions. For performance reasons we must use some cache, the only option seems to be the standard shared $CFG->cachedir/theme/. Using localcachedir is not an option here, we might try to improve the general performance here and if possible skip all caching in theme designer mode.

''Theme caching was improved in 2.6, it is using localcachedir, see MDL-40563.''

==Javascript caching==

We used JS caching in cachedir for performance reasons because we were doing on-the-fly JS compression. Ideally we should switch to build system for all JS files and store the minimised files along the source files in git and just add proper headers in lib/javascript.php script.

''JavaScript caching was improved in 2.6, it is using localcachedir, see MDL-40546.''

==Language installation and customisations==

Each string is constructed from the following sources:
# en pack in plugin/core - always distributed with plugin
# current language pack, including all its parents - downloaded into $CFG->langotherroot (usually $CFG->dataroot/lang)
# local string tweaks - created with tool_customlang, stored in $CFG->langlocalroot in directories with "_local" suffix (usually $CFG->dataroot/lang)

We can use existing $CFG->langrev in cache keys to add support for local lang caches on cluster nodes.

Please note that language packs and local modifications are PHP files, you need to verify file timestamps or blacklist these locations in OP code caches on cluster nodes.

There is another cache for available translations which is stored in $CFG->langmenucachefile, we can move this to MUC and allow local node caches too.

''Lang caching is improved in 2.6, see MDL-41019.''

==PHP accelerators==

Potential problems:
* file time stamps must be verified in Moodle 2.5 and bellow

===opcache extension===

Standard ''opcache'' extension is strongly recommended for Moodle 2.6 forward, it is the only solution officially supported by PHP developers. Starting with Moodle 2.6 we should recommend the opcache extension during environment test. All other PHP accelerators should be actively discourage (warning on environment page).

Please note that HQ developers are not required to test current stable branches with any PHP accelerators.

The goal is to use opcaching without checking of file modification times - problem here are dynamically generated PHP files that are stored in dataroot (component cache, lang packs, local lang modifications, muc config, etc.), we need to invalidate the op code cache explicitly.

''OPcache extension is fully supported in Moodle 2.6, see MDL-40415.''

==Browser sessions==

User session data should be stored in some reliable shared storage, all cluster nodes need to operate with the same session data, the data must not be disappearing randomly.

All sessions drivers should be updating the list of active sessions in the session table, the serialised session data can be stored somewhere else.

Moodle session drivers need to support some special features:
* Session timeout is controlled from Moodle code - it is required for reliable SSO implementations.
* We need to be able to query list of all sessions belonging to one user - this allows us to logout deleted users (for example spammers).
* Locking is strongly recommended because race conditions may create hard to diagnose problems - users need to logout/login to recover from these problems.
* Sometimes the structure of session data changes and then upgrade requires logout of all active users.
* Some add-ons/patches use the information from sessions table to implement limits for concurrent user logins.

By default new installations are using a databases session driver with locking support. There is a legacy file based session driver for sites that cannot use db sessions, but it does not support any advanced features above and is therefore not recommended.

PHP lacks a reliable cross-platform locking support, this is one if major problems when implementing new session drivers. Without locking the changes in user session may be lost resulting in hard to diagnose problems. Another problem when adding new session driver is that the sessions table needs to be updated at least once per minute.

* MDL-31501 is the ticket for implementing a workable memcached session storage backend.
* MDL-25500 is the ticket to implement a general locking mechanism.

''Not implemented yet.''

==File pool==

At present there is a filedir in dataroot where we store all contents of files in Moodle. Theoretically the code could be abstracted to allow storage of file contents in non-filesystem storage.

The default location is $CFG->dataroot/filedir, alterantive value can be specified in $CFG->filedir setting. $CFG->filedir does not require locking, it may be outside of $CFG->dataroot. The file system/sharing may use very aggressive caching techniques because the files never change, the node needs to contact the master when writing or on cache miss.

The original idea was to have a setting for preventing of file removals from the $CFG->filedir directory, this would allow you to put files from multiple installations into just one giant file pool that could be replicated to all nodes - files would be only added there and never deleted automatically. The only potential problem is size of this huge dir and there would have to be a special new tool that exports used files from one site to another that is not using the shared file pool. The setting was supposed to be in file_storage::deleted_file_cleanup() method (one if that simply exits method).

MDL-40528 contains a refactoring of trashdir operations that could help anybody who decides to reimplement the fole_storage class. The sample backup recovery class might be also user for simple local filedir cache on cluster nodes.

==Installation procedure==

1. Build a 1 node cluster
- NFS backing storage
- Configuration parameters like there are lots of nodes
- Database setup on own host and such.
- Build load balancer configuration.
- Run moodle install cli
- Add appropriate configuration items to get the system working behind load balancer
2. Add more nodes to the cluster by replicating the first node.

==Upgrade procedure==

===Sample estimation===
# tweak load balancer to redirect all users to some static non-moodle page
# shutdown all nodes except one
# optionally enable CLI maintenance mode
# upload new PHP files to all nodes
# rebuild component cache if alternative read only location used
# upgrade the node from CLI
# disable CLI maintenance mode
# start other nodes (this guarantees localcachedir and tempdir purging)
# enable normal operation

===Large in-house NFS backend VM upgrade===
CLI Maintenance mode may be useful, but either way, you we stop all web nodes and also ensure that the current cron run has finished, otherwise you can get into all sort of strife. Trying to do an upgrade during the forum digest time or stats run is not possible. Both can run for >1 hour.

Opcode resets are a problem when moving from CLI to apache for fcgi. As I understand it, each has its own opcache location and that needs to be managed properly. Hence the just shutdown the web nodes to force resets.

1. Disable all users except administrator who is upgrading. (This is done via IP at our load balancer)
2. Stop apache on all nodes
3. Stop cron from running and ensure it's finished.

We then ignore the fact we are in a cluster for a few instructions and operate on one node.

3.1 Backup/snapshot database and dataroot

4. Upload new php files to 'master' node.
5. Upgrade 'master' node. admin/cli/upgrade.php
6. Start up 'master' node apache, and test with admin login.
7. If all successful, copy code to all other nodes
8. Turn on other nodes.
9. Browse around a bit to ensure you have warmed the opcache (cold cache can cause floods with 500+ users logging in within 10 seconds of go-live)
10. Turn the system back on for all users.

==Database clustering==

Anything ACID compliant should be ok. For example even-odd master-master MySQL is not ok.

TODO: add descriptions of ACID compliant DB cluster setups

==More information==

* [http://thamblings.blogspot.cz/2013/07/deploying-moodle-continued.html Deploying Moodle]
* [https://docs.moodle.org/25/en/Server_cluster Server cluster (user docs)]

Server clustering improvements proposal

2015-07-21T02:05:49Z

Skodak: /* $CFG->tempdir */

{{Moodle 2.6}}

Author: [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 4 July 2013 (WST) and others

MDL-40979 was raised to group together this issues that are raised out of this document and the discussion. All issues should be linked to that EPIC.

==Cluster configuration requirements==

# Cluster node clocks must be synchronised with difference <1s.
# Database setup must be ACID compliant.
# $CFG->dataroot must be a shared directory.
# $CFG->cachedir must be a shared directory.

Note that these last two often cause confusion. These directories must be shared because Moodle code relies on that, all cluster nodes must see the same data there. Cluster headaches do occur when there is a lot of data in here, so our aim is to REDUCE dependence on shared caches as much as possible, technically it is not possible to have only local caches.

==config.php settings==
Each node in cluster may use local set of php files including config.php, these may be synchronised via git for example, rsync, etc.

===$CFG->wwwroot===
It must be the same on all nodes, it must be the public facing URL. It cannot be dynamic.

===$CFG->sslproxy===
Enable if you have https:// wwwroot but the SSL is not done by Apache.

Do not forget to enable ''Secure cookies only'' to make your site really secure, without it cookie stealing is still trivial.

===$CFG->reverseproxy===
Enable if your nodes are accessed via different URL. Please note that it is not compatible with $CFG->loginhttps.

===$CFG->dirroot===
It is strongly recommended that $CFG->dirroot (which is automatically set via realpath(config.php)) contains the same path on all nodes. It does not need to point to the same shared directory though. The reason is that some some low level code may use the dirroot value for cache invalidation.

The simplest solution is to have the same directory structure on each cluster node and synchronise these during each upgrade.

The dirroot should be always read only for apache process because otherwise built in add-on installation and plugin uninstallation would get the nodes out of sync.

===$CFG->dataroot===

This '''MUST''' be a shared directory where each cluster node is accessing the files directly. It must be very reliable, administrators cannot manipulate files directly there.

Locking support is not required, if any code tries to use file locks in dataroot outside of cachedir or muc directory it is a bug.

===$CFG->tempdir===

'''Requirement: $CFG->cachedir is a directory shared by all cluster nodes.'''

The contents of this directory may be deleted if there is no pending HTTP request.

In 2.9 and later user request directory where possible.

===$CFG->cachedir===

'''Requirement: $CFG->cachedir is a directory shared by all cluster nodes.'''

Cache invalidation is done by deleting or overriding of existing files, this needs to be automatically replicated to all cluster nodes, otherwise the cache may return stale or invalid data which often leads to fatal errors or data loss.

The existing documentation clearly states that this directory must be shared, all existing code including add-ons may expect this, it is therefore not possible to change this requirement without breaking backwards compatibility.

Please note that MUC caches have similar problem, the current design expects that each node is contacting the same caches. It should be possible to create new MUC backends that do not require shared cache backends in a way similar to the proposed $CFG->localcachedir .

You can safely purge cachedir when restarting the whole cluster, you may get some notices or temporary errors if you purge this directory while other requests are active.

Netspot admins came up with a hypothesis that "cachedir does not have to be shared", it is easy to disapprove it - we need to find a single case where the sharing is required. Let's look at the caching of data from config table in $CFG global variable. If one node modifies CFG value others would not be notified about the change and would continue using stale value. Workaround seems to be to create a new revision number that is incremented after any change in $CFG and share it with all nodes. The question is where to put it so that it is shared by all nodes? Storing it in database would require one extra read on each page and one extra write on each update, that is not acceptable. We cannot put the revision into a shared filesystem because we would not have it. We cannot rely on presence of memcache or any shared data storage in default installation either. In most other cases we store the revision flags in CFG itself, it is clearly not possible in this case because it would not be shared by nodes. Somebody said "but it works without sharing for all our clients for at least a year" - that does not prove anything, you would have to make sure it works also for everybody else with all add-ons, custom modifications and minimal number of PHP extensions required by Moodle.

In any case cachedir is shared by definition since the beginning of its existence, it is a fact that developers writing code may depend on. If you do not like it then use local cache dir.

== New $CFG->localcachedir==

The difference from normal $CFG->cachedir is that the directory does not have to be shared by all cluster nodes, the files stored in $CFG->localcachedir MUST NOT change! Default directory is "$CFG->dataroot/localcache".

All files there must use unique revision numbers or hashes because the cached data cannot be invalidated by other mechanism - it will support only adding of new files, but no file deletes or overrides. The $CFG->localcachedir will be growing over time, all local cache files will be deleted during purge_all_caches() (automatically during upgrades).

When using hashes please make sure the number of files in one directory is kept to some reasonable number because some filesystems might have problems with large number of files in one directory.

Note that some caches cannot be easily moved to localcachedir because you need a reliable revision number here, but sometimes it is either not possible or very slow because you need to store the revision number somewhere and you need to bump up the revision number after any change and you would need to store it in database. Caching is not free, each usage must be carefully evaluated.

Design requirements:
* Everything must be automatic without extra administrative overhead.
* purge_all_caches() on any node triggers local cache purging on all other nodes before adding any new files there.
* Performance on standalone servers must not be worse.

Usage restrictions:
* No file deletes
* No file modifications
* No file overwriting
* Soft limit on maximum number of files in one directory (few thousands)

Benefits:
* Clustered servers may use fast local filesystem such as tempfs.
* No opcache cache invalidation problems if php files included from localcachedir (because the files must not change).

Candidates for migration from $CFG->cachedir:
* JS cache MDL-40546
* Theme caches MDL-40563
* HTMLPurifier cache MDL-41017

''Implemented in Moodle 2.6, see MDL-40545.''

==Component cache==

Class core_component is using a $CFG->cachedir/core_component.php cache that contains a complete list of all plugins and all classes present in $CFG->dirroot. The implementation must be as fast as possible and the results must be extremely reliable.

The cache is automatically invalidated on admin/index.php page and during installation and every upgrade. It is also cleared during purge_all_caches(), but that is only a side effect of storing it in cachedir and it is not required.

core_component class cannot depend on database, MUC or any core libraries - that is the reason why there cannot be any revision flag, there is nowhere to store it, the sha1() of that file content would be the revision. But we would have to go through all plugin directories to find out if it was changed or what revision to use. There are only two options - either we store this file in shared cache or admin invalidates this cache manually, the second option it clearly not acceptable for standard installations.

===Alternative component cache location===

This is useful for clustered installations only. Typically the $CFG->alternative_component_cache = '/local/cache/dir/core_component.php' would point to local node cache directory. Before upgrade the administrator would have to manually execute following on each node:

<code>
$ php admin/cli/alternative_component_cache.php --rebuild
</code>

Alternatively you could put the cache file directly into dirroot and distribute it together with new PHP source files. Yet another possibility would be to purge all local caches on all nodes before upgrade or simply change the script name in config.php on all nodes before upgrade.

''Implemented in Moodle 2.6, see MDL-40475.''

==MUC and clustering==

At present administrators are free to create new stores and assign them to existing definitions of each cache. Unfortunately the documentation or admin UI does not mention that by default all those definitions require cache stores to be shared by all cluster nodes! Some cache keys may include revision numbers and all settings which makes them compatible with local caches, we need to document it somewhere.

I would like to propose a new flag in cache definition '''localcache''' which would indicate that it is safe to use local cache stores on cluster nodes. For now we can at least document it in db/caches.php as inline comments. This information should be clearly visible on the cache store/definition settings page. Maybe we could add setting to cache stores which indicates if it is a shared or local cache. The only potential problem is that it might confuse admins that know little about clustering or cache invalidation.

In theory the installation could create two file stores by default - one using current $CFG->cachedir and second using $CFG->localcachedir and assign them to definitions based on localcache flag. This could help new admins when setting up clusters, all they would have to do would be to move localcachedir to cluster node ram disks.

Note that MODE_REQUEST are local by definition and MODE_SESSION are always shared (because session is shared), this means we need to consider only MODE_APPLICATION definitions here.

List of caches/definitions that are compatible with local caching on cluster nodes:
* core htmlpurifier - MDL-41017
* core string - MDL-41019
* core langmenucache - MDL-41019
*

==Theme caching==

''All large installs and clusters should use transparent proxies (such as Cloudflare or custom nginx).''

Small installs without transparent caches (or when in designer mode) depend on performance of theme serving scripts (theme/image.php, theme/styles.php, etc.).

The serving scripts receive revision number in URL, this solves the problem with cache invalidation. We are not using MUC there intentionally because we are not in already open HTTP request with database connection and all standard libraries already loaded, the data there must be served quickly with as little memory and CPU cycles as possible.

The standard theme caches may be stored in local node caches, we could store the theme caches in $CFG->localcachedir/theme/ directory.

Theme designer mode is not using any revisions. For performance reasons we must use some cache, the only option seems to be the standard shared $CFG->cachedir/theme/. Using localcachedir is not an option here, we might try to improve the general performance here and if possible skip all caching in theme designer mode.

''Theme caching was improved in 2.6, it is using localcachedir, see MDL-40563.''

==Javascript caching==

We used JS caching in cachedir for performance reasons because we were doing on-the-fly JS compression. Ideally we should switch to build system for all JS files and store the minimised files along the source files in git and just add proper headers in lib/javascript.php script.

''JavaScript caching was improved in 2.6, it is using localcachedir, see MDL-40546.''

==Language installation and customisations==

Each string is constructed from the following sources:
# en pack in plugin/core - always distributed with plugin
# current language pack, including all its parents - downloaded into $CFG->langotherroot (usually $CFG->dataroot/lang)
# local string tweaks - created with tool_customlang, stored in $CFG->langlocalroot in directories with "_local" suffix (usually $CFG->dataroot/lang)

We can use existing $CFG->langrev in cache keys to add support for local lang caches on cluster nodes.

Please note that language packs and local modifications are PHP files, you need to verify file timestamps or blacklist these locations in OP code caches on cluster nodes.

There is another cache for available translations which is stored in $CFG->langmenucachefile, we can move this to MUC and allow local node caches too.

''Lang caching is improved in 2.6, see MDL-41019.''

==PHP accelerators==

Potential problems:
* file time stamps must be verified in Moodle 2.5 and bellow

===opcache extension===

Standard ''opcache'' extension is strongly recommended for Moodle 2.6 forward, it is the only solution officially supported by PHP developers. Starting with Moodle 2.6 we should recommend the opcache extension during environment test. All other PHP accelerators should be actively discourage (warning on environment page).

Please note that HQ developers are not required to test current stable branches with any PHP accelerators.

The goal is to use opcaching without checking of file modification times - problem here are dynamically generated PHP files that are stored in dataroot (component cache, lang packs, local lang modifications, muc config, etc.), we need to invalidate the op code cache explicitly.

''OPcache extension is fully supported in Moodle 2.6, see MDL-40415.''

==Browser sessions==

User session data should be stored in some reliable shared storage, all cluster nodes need to operate with the same session data, the data must not be disappearing randomly.

All sessions drivers should be updating the list of active sessions in the session table, the serialised session data can be stored somewhere else.

Moodle session drivers need to support some special features:
* Session timeout is controlled from Moodle code - it is required for reliable SSO implementations.
* We need to be able to query list of all sessions belonging to one user - this allows us to logout deleted users (for example spammers).
* Locking is strongly recommended because race conditions may create hard to diagnose problems - users need to logout/login to recover from these problems.
* Sometimes the structure of session data changes and then upgrade requires logout of all active users.
* Some add-ons/patches use the information from sessions table to implement limits for concurrent user logins.

By default new installations are using a databases session driver with locking support. There is a legacy file based session driver for sites that cannot use db sessions, but it does not support any advanced features above and is therefore not recommended.

PHP lacks a reliable cross-platform locking support, this is one if major problems when implementing new session drivers. Without locking the changes in user session may be lost resulting in hard to diagnose problems. Another problem when adding new session driver is that the sessions table needs to be updated at least once per minute.

* MDL-31501 is the ticket for implementing a workable memcached session storage backend.
* MDL-25500 is the ticket to implement a general locking mechanism.

''Not implemented yet.''

==File pool==

At present there is a filedir in dataroot where we store all contents of files in Moodle. Theoretically the code could be abstracted to allow storage of file contents in non-filesystem storage.

The default location is $CFG->dataroot/filedir, alterantive value can be specified in $CFG->filedir setting. $CFG->filedir does not require locking, it may be outside of $CFG->dataroot. The file system/sharing may use very aggressive caching techniques because the files never change, the node needs to contact the master when writing or on cache miss.

The original idea was to have a setting for preventing of file removals from the $CFG->filedir directory, this would allow you to put files from multiple installations into just one giant file pool that could be replicated to all nodes - files would be only added there and never deleted automatically. The only potential problem is size of this huge dir and there would have to be a special new tool that exports used files from one site to another that is not using the shared file pool. The setting was supposed to be in file_storage::deleted_file_cleanup() method (one if that simply exits method).

MDL-40528 contains a refactoring of trashdir operations that could help anybody who decides to reimplement the fole_storage class. The sample backup recovery class might be also user for simple local filedir cache on cluster nodes.

==Installation procedure==

1. Build a 1 node cluster
- NFS backing storage
- Configuration parameters like there are lots of nodes
- Database setup on own host and such.
- Build load balancer configuration.
- Run moodle install cli
- Add appropriate configuration items to get the system working behind load balancer
2. Add more nodes to the cluster by replicating the first node.

==Upgrade procedure==

===Sample estimation===
# tweak load balancer to redirect all users to some static non-moodle page
# shutdown all nodes except one
# optionally enable CLI maintenance mode
# upload new PHP files to all nodes
# rebuild component cache if alternative read only location used
# upgrade the node from CLI
# disable CLI maintenance mode
# start other nodes (this guarantees localcachedir and tempdir purging)
# enable normal operation

===Large in-house NFS backend VM upgrade===
CLI Maintenance mode may be useful, but either way, you we stop all web nodes and also ensure that the current cron run has finished, otherwise you can get into all sort of strife. Trying to do an upgrade during the forum digest time or stats run is not possible. Both can run for >1 hour.

Opcode resets are a problem when moving from CLI to apache for fcgi. As I understand it, each has its own opcache location and that needs to be managed properly. Hence the just shutdown the web nodes to force resets.

1. Disable all users except administrator who is upgrading. (This is done via IP at our load balancer)
2. Stop apache on all nodes
3. Stop cron from running and ensure it's finished.

We then ignore the fact we are in a cluster for a few instructions and operate on one node.

3.1 Backup/snapshot database and dataroot

4. Upload new php files to 'master' node.
5. Upgrade 'master' node. admin/cli/upgrade.php
6. Start up 'master' node apache, and test with admin login.
7. If all successful, copy code to all other nodes
8. Turn on other nodes.
9. Browse around a bit to ensure you have warmed the opcache (cold cache can cause floods with 500+ users logging in within 10 seconds of go-live)
10. Turn the system back on for all users.

==Database clustering==

Anything ACID compliant should be ok. For example even-odd master-master MySQL is not ok.

TODO: add descriptions of ACID compliant DB cluster setups

==More information==

* [http://thamblings.blogspot.cz/2013/07/deploying-moodle-continued.html Deploying Moodle]
* [https://docs.moodle.org/25/en/Server_cluster Server cluster (user docs)]

Developer meeting April 2015

2015-04-19T21:08:42Z

Skodak: /* Timezones handling */

[[Developer meetings]] > April 2015 meeting notes

{| class="nicetable"
|-
| Time
| [http://www.timeanddate.com/worldclock/fixedtime.html?year=2015&month=4&day=21&hour=07&min=0&sec=0 07:00 UTC on Tuesday, 21 April 2015] [http://www.google.com/calendar/event?action=TEMPLATE&text=Moodle+General+developer+meeting&dates=20150421T070000Z/20150421T090000Z&details=&location= Add to my calendar]
|-
| Meeting room
| [http://www.youtube.com/watch?v=g329dAC_oqI Live stream at YouTube]
|-
| Forum discussion
| [https://moodle.org/mod/forum/discuss.php?d=311824 GDF thread]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Event page
| [https://plus.google.com/events/c003f0fctdrmd3oo9dn6jpbpqu4 Google+ event page]
|}

== Agenda ==

The meeting focuses on changes in the upcoming Moodle 2.9 release with special attention paid to impact of these changes on community contributors and plugin authors.

Work in progress - individual items to be confirmed, the exact order is subject of change.

=== Navigation improvements ===

=== First experiences with mustache, the new template framework ===

* by [https://moodle.org/user/profile.php?id=25214 Urs Hunkler] (confirmed)
* See [https://moodle.org/mod/forum/discuss.php?d=311119 the discussion] for more details.

To see how to work with the Moodle Mustache implementation I refactored the »clean« theme to a Mustache theme. The process went quite well. I'll try to show the main thoughts and steps in the refactoring process in about 10 minutes. We may have some time to talk about Moodle Mustache afterwards.

You may have a look at the theme »cleanm« in my [https://github.com/uhunkler/moodle/tree/MOODLE_29_mustaches Git repo].

[[User:Urs Hunkler|Urs Hunkler]] ([[User talk:Urs Hunkler|talk]]) 23:32, 13 April 2015 (AWST)

=== Unified AJAX script handler ===

* MDL-49163

=== Timezones handling ===

* by [https://moodle.org/user/profile.php?id=12863 Petr Škoda] (confirmed)
* MDL-49684
Moodle 2.9 is switching to native PHP date and time code. The old homegrown DST switching routines were completely removed. Instead of downloading the timezone.txt file administrators need to keep their PHP timezone up-to-date. There are still some remaining date/time bugs throughout the codebase, but this change makes the fixing much easier because developers may finally use the DateTime class or legacy date functions in PHP.

=== Per-request temp directories ===

* by Andrew Nicols
* MDL-44874

=== Behat tests runs in parallel ===

* by Rajesh Taneja
* MDL-39752
As we have over 33000 behat steps in moodle and it's growing rapidly. It takes around 12 hours to execute whole behat suite, which is not expectable for any testing environment. With initial work from Tony and Damyon, we came up with strategy of splitting feature files in different processes and run them in parallel. I will try cover options and demo for running behat in parallel.

== More ==

* If you have something you'd like to add to this page, please contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

Developer meeting April 2015

2015-04-19T21:08:01Z

Skodak: /* Timezones handling */

[[Developer meetings]] > April 2015 meeting notes

{| class="nicetable"
|-
| Time
| [http://www.timeanddate.com/worldclock/fixedtime.html?year=2015&month=4&day=21&hour=07&min=0&sec=0 07:00 UTC on Tuesday, 21 April 2015] [http://www.google.com/calendar/event?action=TEMPLATE&text=Moodle+General+developer+meeting&dates=20150421T070000Z/20150421T090000Z&details=&location= Add to my calendar]
|-
| Meeting room
| [http://www.youtube.com/watch?v=g329dAC_oqI Live stream at YouTube]
|-
| Forum discussion
| [https://moodle.org/mod/forum/discuss.php?d=311824 GDF thread]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Event page
| [https://plus.google.com/events/c003f0fctdrmd3oo9dn6jpbpqu4 Google+ event page]
|}

== Agenda ==

The meeting focuses on changes in the upcoming Moodle 2.9 release with special attention paid to impact of these changes on community contributors and plugin authors.

Work in progress - individual items to be confirmed, the exact order is subject of change.

=== Navigation improvements ===

=== First experiences with mustache, the new template framework ===

* by [https://moodle.org/user/profile.php?id=25214 Urs Hunkler] (confirmed)
* See [https://moodle.org/mod/forum/discuss.php?d=311119 the discussion] for more details.

To see how to work with the Moodle Mustache implementation I refactored the »clean« theme to a Mustache theme. The process went quite well. I'll try to show the main thoughts and steps in the refactoring process in about 10 minutes. We may have some time to talk about Moodle Mustache afterwards.

You may have a look at the theme »cleanm« in my [https://github.com/uhunkler/moodle/tree/MOODLE_29_mustaches Git repo].

[[User:Urs Hunkler|Urs Hunkler]] ([[User talk:Urs Hunkler|talk]]) 23:32, 13 April 2015 (AWST)

=== Unified AJAX script handler ===

* MDL-49163

=== Timezones handling ===

* by [https://moodle.org/user/profile.php?id=12863 Petr Škoda] (confirmed)
* MDL-49684
Moodle 2.9.0 is switching to native PHP date and time code. The old homegrown DST switching routines were completely removed. Instead of downloading the timezone.txt file administrators need to keep their PHP timezone up-to-date. There are still some remaining date/time bugs throughout the codebase, but this change makes the fixing much easier because developers may finally use the DateTime class or legacy date functions in PHP.

=== Per-request temp directories ===

* by Andrew Nicols
* MDL-44874

=== Behat tests runs in parallel ===

* by Rajesh Taneja
* MDL-39752
As we have over 33000 behat steps in moodle and it's growing rapidly. It takes around 12 hours to execute whole behat suite, which is not expectable for any testing environment. With initial work from Tony and Damyon, we came up with strategy of splitting feature files in different processes and run them in parallel. I will try cover options and demo for running behat in parallel.

== More ==

* If you have something you'd like to add to this page, please contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

Developer meeting April 2015

2015-04-19T21:03:24Z

Skodak: /* Timezones handling */

[[Developer meetings]] > April 2015 meeting notes

{| class="nicetable"
|-
| Time
| [http://www.timeanddate.com/worldclock/fixedtime.html?year=2015&month=4&day=21&hour=07&min=0&sec=0 07:00 UTC on Tuesday, 21 April 2015] [http://www.google.com/calendar/event?action=TEMPLATE&text=Moodle+General+developer+meeting&dates=20150421T070000Z/20150421T090000Z&details=&location= Add to my calendar]
|-
| Meeting room
| [http://www.youtube.com/watch?v=g329dAC_oqI Live stream at YouTube]
|-
| Forum discussion
| [https://moodle.org/mod/forum/discuss.php?d=311824 GDF thread]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Event page
| [https://plus.google.com/events/c003f0fctdrmd3oo9dn6jpbpqu4 Google+ event page]
|}

== Agenda ==

The meeting focuses on changes in the upcoming Moodle 2.9 release with special attention paid to impact of these changes on community contributors and plugin authors.

Work in progress - individual items to be confirmed, the exact order is subject of change.

=== Navigation improvements ===

=== First experiences with mustache, the new template framework ===

* by [https://moodle.org/user/profile.php?id=25214 Urs Hunkler] (confirmed)
* See [https://moodle.org/mod/forum/discuss.php?d=311119 the discussion] for more details.

To see how to work with the Moodle Mustache implementation I refactored the »clean« theme to a Mustache theme. The process went quite well. I'll try to show the main thoughts and steps in the refactoring process in about 10 minutes. We may have some time to talk about Moodle Mustache afterwards.

You may have a look at the theme »cleanm« in my [https://github.com/uhunkler/moodle/tree/MOODLE_29_mustaches Git repo].

[[User:Urs Hunkler|Urs Hunkler]] ([[User talk:Urs Hunkler|talk]]) 23:32, 13 April 2015 (AWST)

=== Unified AJAX script handler ===

* MDL-49163

=== Timezones handling ===

* by [https://moodle.org/user/profile.php?id=12863 Petr Škoda] (confirmed)
* MDL-49684
Moodle 2.9.0 is switching to native PHP date and time code. The old homegrown DST switching routines were completely removed.

=== Per-request temp directories ===

* by Andrew Nicols
* MDL-44874

=== Behat tests runs in parallel ===

* by Rajesh Taneja
* MDL-39752
As we have over 33000 behat steps in moodle and it's growing rapidly. It takes around 12 hours to execute whole behat suite, which is not expectable for any testing environment. With initial work from Tony and Damyon, we came up with strategy of splitting feature files in different processes and run them in parallel. I will try cover options and demo for running behat in parallel.

== More ==

* If you have something you'd like to add to this page, please contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

Developer meeting October 2014

2014-10-20T19:48:51Z

Skodak:

[[Developer meetings]] > October 2014 meeting notes

{| class="nicetable"
|-
| Time
| [http://timeanddate.com/worldclock/fixedtime.html?year=2014&month=10&day=21&hour=13&min=0&sec=0 13:00 UTC on Tuesday, 21 October 2014]
|-
| Meeting room
| [https://www.youtube.com/watch?v=lc4rOo6Tu_o Live stream at YouTube]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Event page
| [https://plus.google.com/events/ctssr21hp0nitv3i8vg5l4aa3t8 Google+]
|}

This meeting will focus on the impending release.

The meeting will be streamed live on YouTube with chat through the regular Dev chat room and comments on Twitter.

== Agenda ==
; Moodle 2.8 overview: by Martin Dougiamas, see [[Moodle 2.8 release notes]]
; Inbound Message API: by Andrew Nicols, MDL-46282
; String deprecation process: by Marina Glancy and David Mudrák, MDL-46585, see [[String deprecation]]
; Assignment table restructure: by Damyon Wiese, MDL-46171, see [https://github.com/moodle/moodle/blob/master/mod/assign/upgrade.txt mod/assign/upgrade.txt]
; Mobile App development news and roadmap: by Juan Leyva
; Plugins directory news and roadmap: by David Mudrák ([https://moodle.org/mod/forum/view.php?id=8149 plugins traffic blog], [https://moodle.org/plugins/browse.php?list=award&id=2 featured plugins])
; The future of MNet: see [[MNet Roadmap]]
; Proposal for making the quiz continue to work when the internet connection drops: by Tim Hunt, MDL-47688.
; Date/Time/Timezone cleanup: proposed by Petr Skoda

If you have something you'd like to add to this page, please edit this page or contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

== Questions from the audience ==

# How is Moodle HQ reacting to the developer community reaction to the new logging/event system? ( [https://moodle.org/mod/forum/discuss.php?d=272042 very] [https://moodle.org/mod/forum/discuss.php?d=267920 many] [https://moodle.org/mod/forum/discuss.php?d=256457 related] [https://moodle.org/mod/forum/discuss.php?d=257934 threads])
# Does Moodle HQ have a response to Yahoo's recent announcement that it has removed support for YUI (discussed [https://moodle.org/mod/forum/discuss.php?d=268190 here])?
# Are there any goodies for the upcoming version of Moodle 3 that you are targeting in the long-term roadmap?

Developer meeting October 2014

2014-10-16T02:23:43Z

Skodak: /* Agenda */

[[Developer meetings]] > October 2014 meeting notes

{| class="nicetable"
|-
| Time
| [http://timeanddate.com/worldclock/fixedtime.html?year=2014&month=10&day=21&hour=13&min=0&sec=0 13:00 UTC on Tuesday, 21 October 2014]
|-
| Meeting room
| [https://www.youtube.com/watch?v=lc4rOo6Tu_o Live stream at YouTube]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Event page
| [https://plus.google.com/events/ctssr21hp0nitv3i8vg5l4aa3t8 Google+]
|}

This meeting will focus on the impending release.

The meeting will be streamed live on YouTube with chat through the regular Dev chat room and comments on Twitter.

== Agenda ==
; Moodle 2.8 overview: by Martin Dougiamas, see [[Moodle 2.8 release notes]]
; Inbound Message API: by Andrew Nicols, MDL-46282
; String deprecation process: by Marina Glancy and David Mudrák, MDL-46585, see [[String deprecation]]
; Assignment table restructure: by Damyon Wiese, MDL-46171, see [https://github.com/moodle/moodle/blob/master/mod/assign/upgrade.txt mod/assign/upgrade.txt]
; Mobile App development news and roadmap: by Juan Leyva
; Featured plugins in the plugins directory: by David Mudrák, see [https://moodle.org/mod/forum/view.php?id=8149 plugins traffic blog] and [https://moodle.org/plugins/browse.php?list=award&id=2 their list].
; The future of MNet: see [[MNet Roadmap]]
; Proposal for making the quiz continue to work when the internet connection drops: by Tim Hunt, MDL-47688.
; Data/timezone cleanup: proposed by Petr Skoda

If you have something you'd like to add to this page, please edit this page or contact [https://moodle.org/user/profile.php?id=1601 David Mudrák].

== Questions from the audience ==

# How is Moodle HQ reacting to the developer community reaction to the new logging/event system? ( [https://moodle.org/mod/forum/discuss.php?d=272042 very] [https://moodle.org/mod/forum/discuss.php?d=267920 many] [https://moodle.org/mod/forum/discuss.php?d=256457 related] [https://moodle.org/mod/forum/discuss.php?d=257934 threads])
# Does Moodle HQ have a response to Yahoo's recent announcement that it has removed support for YUI (discussed [https://moodle.org/mod/forum/discuss.php?d=268190 here])?
# Are there any goodies for the upcoming version of Moodle 3 that you are targeting in the long-term roadmap?

Events API

2014-10-14T22:22:32Z

Skodak: /* Accuracy */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objectid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters - indicating 'c'reate, 'r'ead, 'u'pdate or 'd'elete operation. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the logging subsystem, and cannot be used later when logged event is displayed.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

It is important to trigger individual events for each and every action, bulk events are very strongly discouraged because existing observers would not receive important information. Changes from one to many would break backwards compatibility with observers and reporting.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T22:19:27Z

Skodak: /* Accuracy */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objectid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters - indicating 'c'reate, 'r'ead, 'u'pdate or 'd'elete operation. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the logging subsystem, and cannot be used later when logged event is displayed.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

It is important to trigger individual events for each and every action, bulk events are very strongly discouraged.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T22:16:27Z

Skodak: /* Record caching */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objectid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters - indicating 'c'reate, 'r'ead, 'u'pdate or 'd'elete operation. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the logging subsystem, and cannot be used later when logged event is displayed.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T22:12:12Z

Skodak: /* Properties */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objectid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters - indicating 'c'reate, 'r'ead, 'u'pdate or 'd'elete operation. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T22:10:25Z

Skodak: /* Properties */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objectid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:59:54Z

Skodak: /* Triggering events */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events are in namespace '\core\event\'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:58:35Z

Skodak: /* Triggering events */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Event class name is a unique identifier of each event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:57:17Z

Skodak: /* Differences from old event handling */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is a separate record snapshot cache that may be used when deleting data or for observer performance improvements.
# There is no database access in new event dispatching code.
# There is no support for delayed cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:53:05Z

Skodak: /* Event dispatching */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available 'events.php' files from core and all plugins. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Original handlers could not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers of the current event are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:50:00Z

Skodak: /* Event observers */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded during upgrade.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:48:00Z

Skodak: /* Backwards compatibility and migration */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters have been migrated to method get_legacy_log_data() in new events. Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:44:50Z

Skodak: /* Events API */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. During development new event definitions and observers can be added without the need to upgrade, only purging of the MUC cache is required.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters has been migrated inside new events method, in get_legacy_log_data(). Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:43:03Z

Skodak: /* Events API */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions are automatically included when needed, without having to maintain lists of known event types. New event definitions can be added without the need to upgrade, only purging of the MUC cache is required after adding a new observer.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters has been migrated inside new events method, in get_legacy_log_data(). Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:41:15Z

Skodak: /* Events API */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as event description).
; Automatic inclusion
: Event class definitions is automatically included when needed, without having to maintain lists of known event types. New event definitions can be added without the need to upgrade, only purging of the MUC cache is required after adding a new observer.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters has been migrated inside new events method, in get_legacy_log_data(). Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

Events API

2014-10-14T21:39:37Z

Skodak: /* Event observers */

{{Infobox Project
|name = Events 2
|state = Completed
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system. Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why was a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement are useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined for logging and other advanced use cases. They need to contain more information, organised in a standardised way (in addition to the fields from the legacy log table and log_actions table).
* Complex data types were allowed in old events, which was causing major problems when serialising/storing/unserialising the data.
* The logging tables and events contain similar information and were triggered at the same places; utilising events for logging would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system is an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It is possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Previously, handlers did not receive event names which made this problematic.
* Previously, event handlers could trigger exceptions during site upgrades, which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in previous handlers blocked dispatching of subsequent events. Problems in new observers would only be logged and execution would continue normally.
* Previously, execution of external handlers during DB transactions blocked other handlers. This would be eliminated by in-memory buffer for external events.
* Previously there was no observer priority.
* Previously, nested events were not dispatched sequentially, which would change the order of events were received by lower priority handlers.

= Performance =
Some basic profiling was conducted.

This next two paragraphs need to be replaced with results.
There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be implemented in parallel with the old one, which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to capture more information about actions in Moodle by triggering more events and logging more information about each event. This is going to impact negatively on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin defines the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach has several benefits.
; Events are active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object is able to provide callback functions for various purposes (such as capability checks).
; Automatic inclusion
: Event class definitions is automatically included when needed, without having to maintain lists of known event types. New event definitions can be added without the need to upgrade, only purging of the MUC cache is required after adding a new observer.
; Maintainability
: It is relatively simple to add new events and migrate existing events. Code review is simplified because there is less duplication of code when triggering same events and all event related information/code is concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events is combined with the definition of events in one place (file). It is easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs. A list of all events is now available as a report to administrators and researchers.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects unintentional typos.

== Backwards compatibility and migration ==

Events:
* All legacy events in the standard distribution have been replaced with the new events API and events_trigger() has been deprecated.
* For events that already exist in Moodle 2.5, the additional legacy information has been added to the event data (in properties 'legacyeventname' and 'legacyeventdata')
* The legacy events handling code is maintained separately and will continue being supported in Moodle 2.7.
* All legacy events-handlers have been migrated to new observers in standard distribution.
* In future, more subsystems may be migrated to events-observers, ex.: gradebook history, completion.

Logging:
* The function add_to_log() has been deprecated with a notice as of Moodle 2.7.
* Existing add_to_log() parameters has been migrated inside new events method, in get_legacy_log_data(). Calls to core_event_base::trigger() will lead to entries being added to the legacy log table if the legacy log plugin is enabled.

See https://docs.moodle.org/dev/Migrating_logging_calls_in_plugins

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

Observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname – fully qualified event class name or "*" indicating all events, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

'''NOTE: Event observers are cached. If you add or change observers you need to purge the caches or they will not be recognised. Plugin developers need to bump up the version number to guarantee that the list of observers is reloaded.'''

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available in 'events.php' files. Previously handlers were installed only during installation and upgrade. This has little risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of Moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# There is separate context cache that may be used when deleting data or for observer performance improvements.
# No database access is allowed in new event dispatching code.
# There is no support for cron execution. This eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading, which leads to a smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event definitions are classes extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class names are a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Each event class is defined in a separate file. File name and location must match the class name for the use of auto loading, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow the standard naming convention. The last word after the underscore is automatically parsed as its action, the rest of word is its object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of PHP autoloading ===

All new OOP APIs in Moodle 2.6 onwards are going to use class auto loading - see [[Automatic class loading]]. New events use PHP within strictly defined namespaces, which concentrate all event classes in the classes/event/ subdirectory.

=== Why separate classes? ===
Pros
* Maintainability - It is much easier to review, debug and integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatic lists events can be generated without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).
* This has increased the number lines of code in Moodle for events and logging.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delayed computation of data until the time it is really needed, if it ever is.

=== Properties ===

The following is a list of properties that the developer has to pass to the event upon creation, or ones that can be automatically generated where possible and cost free. Some of these properties are not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Required
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| -
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| -
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| -
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| -
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
| static
| optional (Must be set if objetid present)
| Database table name which represents the event object to the best. Never use a relationship table here.
|-
| objectid
| Object ID
| variable
| Optional (Must be set if objettable present)
| Id of the object record from objecttable.
|-
| '''''crud'''''
| Transaction type
| ''static''
| optional
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static''
| optional
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
| -
|-
| contextlevel
| Context level
| automatic from context
| -
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| -
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| -
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| -
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
| variable
| optional
| Is this action related to some user? This could be used for some personal timeline view.
|-
| anonymous
| Anonymous action
| variable
| optional (Defaults to 0)
| Is this action anonymous? Reports should ignore events with anonymous set to 1.
|-
| other
| All other data
| variable array
| optional
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
| -
| Time when the event was triggered.
|}

* static: same for all event instances of this class
* variable: might not be same for all instances of this event class
* mandatory: required in order to trigger the event
* optional: not necessarily required to trigger the event

==== Level property ====

The edulevel property helps define the educational value of the event. It is intentional that the list is limited to only 3 different constants as having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is effecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns non-localised description of one particular event. There are plans to make this localised in future.

It is recommended that the string begins with identifying the user who triggered the event by providing the user id in quotations. This applies to other variables used in the description as well. If an activity is also mentioned then the course module id should be used, not the id from the activity table. For example "The user with the id '$this->userid' updated the activity 'youractivity' with the course module id '$this->contextinstanceid'.".
|-
| can_view($user)
| This method is deprecated, please do not use this.
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards. Can be null, if no valid location is present.
|-
| get_legacy_eventname()
| Information necessary for event backward compatibility.
|-
| get_legacy_eventdata()
| Information necessary for event backward compatibility.
|-
| get_legacy_logdata()
| Information necessary for logging backward compatibility.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc.
* Snapshots are expected to be an exact snapshot of the database table at the instance when the event was triggered.
* Snapshot can be set and requested for any table. If not cached, it defaults to direct $DB->get_record calls.
* Please be aware that the snapshots are not stored in the event, and cannot be restored.
* Snapshot are supposed to be used only by observers. They should never be used by reports or by the event itself.
* When using a snapshot in an observer, please make sure you are taking proper care of handling exceptions as the record you are requesting could have been deleted in the time, in between your observer is notified about the event and the trigger.
* We recommend all delete event must add snapshot of the deleted record.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Existing events ===

List of existing events in Moodle code base, along with their 2.5 couterparts.

This list is out of date. For a full list of events check out the [https://docs.moodle.org/en/Event_list_report Event list report] which is located in "Site administration > Reports > Event list" of your Moodle installation (2.7+).

{| class="nicetable"
|-
! Fully qualified event name
! 2.5 name
! Component
! Object
! Action (Verb)
! Comment
|-
| '''assignsubmission_comments\event\comment_created'''
| -
| assignsubmission_comments
| comment
| created
|
|-
| '''assignsubmission_comments\event\comment_deleted'''
| -
| assignsubmission_comments
| comment
| deleted
|
|-
| '''assignsubmission_file\event\assessable_uploaded'''
| assessable_file_uploaded
| assignsubmission_file
| assessable
| uploaded
| To be deprecated MDL-35197
|-
| '''assignsubmission_file\event\submission_created'''
| -
| assignsubmission_file
| submission
| created
|
|-
| '''assignsubmission_file\event\submission_updated'''
| -
| assignsubmission_file
| submission
| updated
|
|-
| '''assignsubmission_onlinetext\event\assessable_uploaded'''
| assessable_content_uploaded
| assignsubmission_onlinetext
| assessable
| uploaded
|
|-
| '''assignsubmission_onlinetext\event\submission_created'''
| -
| assignsubmission_onlinetext
| submission
| created
|
|-
| '''assignsubmission_onlinetext\event\submission_updated'''
| -
| assignsubmission_onlinetext
| submission
| updated
|
|-
| '''block_comments\event\comment_created'''
| -
| block_comments
| comment
| created
|
|-
| '''block_comments\event\comment_deleted'''
| -
| block_comments
| comment
| deleted
|
|-
| '''booktool_exportimscp\event\book_exported'''
| -
| booktool_exportimscp
| book
| exported
|
|-
| '''booktool_print\event\book_printed'''
| -
| booktool_print
| book
| printed
|
|-
| '''booktool_print\event\chapter_printed'''
| -
| booktool_print
| chapter
| printed
|
|-
| '''core\event\assessable_submitted'''
| -
| core
| assessable
| submitted
| Abstract class
|-
| '''core\event\assessable_uploaded'''
| -
| core
| assessable
| uploaded
| Abstract class
|-
| '''core\event\base'''
| -
| core
| base
| -
| Abstract class
|-
| '''core\event\blog_association_created'''
| -
| core
| blog_association
| created
|
|-
| '''core\event\blog_comment_created'''
| -
| core
| blog_comment
| created
|
|-
| '''core\event\blog_comment_deleted'''
| -
| core
| blog_comment
| deleted
|
|-
| '''core\event\blog_entries_viewed'''
| -
| core
| blog_entries
| viewed
|
|-
| '''core\event\blog_entry_created'''
| blog_entry_added
| core
| blog_entry
| created
|
|-
| '''core\event\blog_entry_deleted'''
| blog_entry_deleted
| core
| blog_entry
| deleted
|
|-
| '''core\event\blog_entry_updated'''
| blog_entry_edited
| core
| blog_entry
| updated
|
|-
| '''core\event\cohort_created'''
| cohort_added
| core
| cohort
| created
|
|-
| '''core\event\cohort_deleted'''
| cohort_deleted
| core
| cohort
| deleted
|
|-
| '''core\event\cohort_member_added'''
| cohort_member_added
| core
| cohort_member
| added
|
|-
| '''core\event\cohort_member_removed'''
| cohort_member_removed
| core
| cohort_member
| removed
|
|-
| '''core\event\cohort_updated'''
| cohort_updated
| core
| cohort
| updated
|
|-
| '''core\event\comment_created'''
| -
| core
| comment
| created
| Abstract class
|-
| '''core\event\comment_deleted'''
| -
| core
| comment
| deleted
| Abstract class
|-
| '''core\event\comments_viewed'''
| -
| core
| comments
| viewed
| Abstract class
|-
| '''core\event\content_viewed'''
| -
| core
| content
| viewed
| Abstract class
|-
| '''core\event\course_category_created'''
| -
| core
| course_category
| created
|
|-
| '''core\event\course_category_deleted'''
| course_category_deleted
| core
| course_category
| deleted
|
|-
| '''core\event\course_category_updated'''
| -
| core
| course_category
| updated
|
|-
| '''core\event\course_completed'''
| course_completed
| core
| course
| completed
|
|-
| '''core\event\course_completion_updated'''
| -
| core
| course_completion
| updated
|
|-
| '''core\event\course_content_deleted'''
| course_content_removed
| core
| course_content
| deleted
|
|-
| '''core\event\course_created'''
| course_created
| core
| course
| created
|
|-
| '''core\event\course_deleted'''
| course_deleted
| core
| course
| deleted
|
|-
| '''core\event\course_module_completion_updated'''
| activity_completion_changed
| core
| course_module_completion
| updated
|
|-
| '''core\event\course_module_created'''
| mod_created
| core
| course_module
| created
|
|-
| '''core\event\course_module_deleted'''
| mod_deleted
| core
| course_module
| deleted
|
|-
| '''core\event\course_module_instance_list_viewed'''
| -
| core
| course_module_instance_list
| viewed
| Abstract class
|-
| '''core\event\course_module_instances_list_viewed'''
| -
| core
| course_module_instances_list
| viewed
| Abstract class
|-
| '''core\event\course_module_updated'''
| mod_updated
| core
| course_module
| updated
|
|-
| '''core\event\course_module_viewed'''
| -
| core
| course_module
| viewed
| Abstract class
|-
| '''core\event\course_reset_ended'''
| -
| core
| course_reset
| ended
|
|-
| '''core\event\course_reset_started'''
| -
| core
| course_reset
| started
|
|-
| '''core\event\course_restored'''
| course_restored
| core
| course
| restored
|
|-
| '''core\event\course_section_updated'''
| -
| core
| course_section
| updated
|
|-
| '''core\event\course_updated'''
| course_updated
| core
| course
| updated
|
|-
| '''core\event\email_failed'''
| -
| core
| email
| failed
|
|-
| '''core\event\group_created'''
| groups_group_created
| core
| group
| created
|
|-
| '''core\event\group_deleted'''
| groups_group_deleted
| core
| group
| deleted
|
|-
| '''core\event\group_member_added'''
| groups_member_added
| core
| group_member
| added
|
|-
| '''core\event\group_member_removed'''
| groups_member_removed
| core
| group_member
| removed
|
|-
| '''core\event\group_updated'''
| groups_group_updated
| core
| group
| updated
|
|-
| '''core\event\grouping_created'''
| groups_grouping_created
| core
| grouping
| created
|
|-
| '''core\event\grouping_deleted'''
| groups_grouping_deleted
| core
| grouping
| deleted
|
|-
| '''core\event\grouping_updated'''
| groups_grouping_updated
| core
| grouping
| updated
|
|-
| '''core\event\manager'''
| -
| core
| manager
| anager
|
|-
| '''core\event\mnet_access_control_created'''
| -
| core
| mnet_access_control
| created
|
|-
| '''core\event\mnet_access_control_updated'''
| -
| core
| mnet_access_control
| updated
|
|-
| '''core\event\note_created'''
| -
| core
| note
| created
|
|-
| '''core\event\note_deleted'''
| -
| core
| note
| deleted
|
|-
| '''core\event\note_updated'''
| -
| core
| note
| updated
|
|-
| '''core\event\notes_viewed'''
| -
| core
| notes
| viewed
|
|-
| '''core\event\role_allow_assign_updated'''
| -
| core
| role_allow_assign
| updated
|
|-
| '''core\event\role_allow_override_updated'''
| -
| core
| role_allow_override
| updated
|
|-
| '''core\event\role_allow_switch_updated'''
| -
| core
| role_allow_switch
| updated
|
|-
| '''core\event\role_assigned'''
| role_assigned
| core
| role
| assigned
|
|-
| '''core\event\role_capabilities_updated'''
| -
| core
| role_capabilities
| updated
|
|-
| '''core\event\role_deleted'''
| -
| core
| role
| deleted
|
|-
| '''core\event\role_unassigned'''
| role_unassigned
| core
| role
| unassigned
|
|-
| '''core\event\user_created'''
| user_created
| core
| user
| created
|
|-
| '''core\event\user_deleted'''
| user_deleted
| core
| user
| deleted
|
|-
| '''core\event\user_enrolment_created'''
| user_enrolled
| core
| user_enrolment
| created
|
|-
| '''core\event\user_enrolment_deleted'''
| user_unenrolled
| core
| user_enrolment
| deleted
|
|-
| '''core\event\user_enrolment_updated'''
| user_enrol_modified
| core
| user_enrolment
| updated
|
|-
| '''core\event\user_list_viewed'''
| -
| core
| user_list
| viewed
|
|-
| '''core\event\user_loggedin'''
| -
| core
| user
| loggedin
|
|-
| '''core\event\user_loggedinas'''
| -
| core
| user
| loggedinas
|
|-
| '''core\event\user_loggedout'''
| user_logout
| core
| user
| loggedout
|
|-
| '''core\event\user_login_failed'''
| -
| core
| user_login
| failed
|
|-
| '''core\event\user_profile_viewed'''
| -
| core
| user_profile
| viewed
|
|-
| '''core\event\user_updated'''
| user_updated
| core
| user
| updated
|
|-
| '''core\event\webservice_function_called'''
| -
| core
| webservice_function
| called
|
|-
| '''core\event\webservice_login_failed'''
| -
| core
| webservice_login
| failed
|
|-
| '''core\event\webservice_service_created'''
| -
| core
| webservice_service
| created
|
|-
| '''core\event\webservice_service_deleted'''
| -
| core
| webservice_service
| deleted
|
|-
| '''core\event\webservice_service_updated'''
| -
| core
| webservice_service
| updated
|
|-
| '''core\event\webservice_service_user_added'''
| -
| core
| webservice_service_user
| added
|
|-
| '''core\event\webservice_service_user_removed'''
| -
| core
| webservice_service_user
| removed
|
|-
| '''core\event\webservice_token_created'''
| -
| core
| webservice_token
| created
|
|-
| '''core\event\webservice_token_sent'''
| -
| core
| webservice_token
| sent
|
|-
| '''logstore_legacy\event\legacy_logged'''
| -
| logstore_legacy
| legacy
| logged
|
|-
| '''mod_assign\event\all_submissions_downloaded'''
| -
| mod_assign
| all_submissions
| downloaded
|
|-
| '''mod_assign\event\assessable_submitted'''
| assessable_submitted
| mod_assign
| assessable
| submitted
|
|-
| '''mod_assign\event\extension_granted'''
| -
| mod_assign
| extension
| granted
|
|-
| '''mod_assign\event\identities_revealed'''
| -
| mod_assign
| identities
| revealed
|
|-
| '''mod_assign\event\marker_updated'''
| -
| mod_assign
| marker
| updated
|
|-
| '''mod_assign\event\statement_accepted'''
| -
| mod_assign
| statement
| accepted
|
|-
| '''mod_assign\event\submission_created'''
| -
| mod_assign
| submission
| created
| Abstract class
|-
| '''mod_assign\event\submission_duplicated'''
| -
| mod_assign
| submission
| duplicated
|
|-
| '''mod_assign\event\submission_graded'''
| -
| mod_assign
| submission
| graded
|
|-
| '''mod_assign\event\submission_locked'''
| -
| mod_assign
| submission
| locked
|
|-
| '''mod_assign\event\submission_status_updated'''
| -
| mod_assign
| submission_status
| updated
|
|-
| '''mod_assign\event\submission_unlocked'''
| -
| mod_assign
| submission
| unlocked
|
|-
| '''mod_assign\event\submission_updated'''
| -
| mod_assign
| submission
| updated
| Abstract class
|-
| '''mod_assign\event\workflow_state_updated'''
| -
| mod_assign
| workflow_state
| updated
|
|-
| '''mod_book\event\chapter_created'''
| -
| mod_book
| chapter
| created
|
|-
| '''mod_book\event\chapter_deleted'''
| -
| mod_book
| chapter
| deleted
|
|-
| '''mod_book\event\chapter_updated'''
| -
| mod_book
| chapter
| updated
|
|-
| '''mod_book\event\chapter_viewed'''
| -
| mod_book
| chapter
| viewed
|
|-
| '''mod_book\event\course_module_instance_list_viewed'''
| -
| mod_book
| course_module_instance_list
| viewed
|
|-
| '''mod_book\event\course_module_viewed'''
| -
| mod_book
| course_module
| viewed
|
|-
| '''mod_chat\event\course_module_instance_list_viewed'''
| -
| mod_chat
| course_module_instance_list
| viewed
|
|-
| '''mod_chat\event\message_sent'''
| -
| mod_chat
| message
| sent
|
|-
| '''mod_chat\event\sessions_viewed'''
| -
| mod_chat
| sessions
| viewed
|
|-
| '''mod_choice\event\answer_submitted'''
| -
| mod_choice
| answer
| submitted
|
|-
| '''mod_choice\event\answer_updated'''
| -
| mod_choice
| answer
| updated
|
|-
| '''mod_choice\event\course_module_instance_list_viewed'''
| -
| mod_choice
| course_module_instance_list
| viewed
|
|-
| '''mod_choice\event\course_module_viewed'''
| -
| mod_choice
| course_module
| viewed
|
|-
| '''mod_choice\event\report_viewed'''
| -
| mod_choice
| report
| viewed
|
|-
| '''mod_data\event\comment_created'''
| -
| mod_data
| comment
| created
|
|-
| '''mod_data\event\comment_deleted'''
| -
| mod_data
| comment
| deleted
|
|-
| '''mod_data\event\course_module_instance_list_viewed'''
| -
| mod_data
| course_module_instance_list
| viewed
|
|-
| '''mod_data\event\course_module_viewed'''
| -
| mod_data
| course_module
| viewed
|
|-
| '''mod_data\event\field_created'''
| -
| mod_data
| field
| created
|
|-
| '''mod_data\event\field_deleted'''
| -
| mod_data
| field
| deleted
|
|-
| '''mod_data\event\field_updated'''
| -
| mod_data
| field
| updated
|
|-
| '''mod_data\event\record_created'''
| -
| mod_data
| record
| created
|
|-
| '''mod_data\event\record_deleted'''
| -
| mod_data
| record
| deleted
|
|-
| '''mod_data\event\record_updated'''
| -
| mod_data
| record
| updated
|
|-
| '''mod_data\event\template_updated'''
| -
| mod_data
| template
| updated
|
|-
| '''mod_data\event\template_viewed'''
| -
| mod_data
| template
| viewed
|
|-
| '''mod_feedback\event\course_module_instance_list_viewed'''
| -
| mod_feedback
| course_module_instance_list
| viewed
|
|-
| '''mod_feedback\event\course_module_viewed'''
| -
| mod_feedback
| course_module
| viewed
|
|-
| '''mod_feedback\event\response_deleted'''
| -
| mod_feedback
| response
| deleted
|
|-
| '''mod_feedback\event\response_submitted'''
| -
| mod_feedback
| response
| submitted
|
|-
| '''mod_folder\event\course_module_instance_list_viewed'''
| -
| mod_folder
| course_module_instance_list
| viewed
|
|-
| '''mod_folder\event\course_module_viewed'''
| -
| mod_folder
| course_module
| viewed
|
|-
| '''mod_folder\event\folder_updated'''
| -
| mod_folder
| folder
| updated
|
|-
| '''mod_forum\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_forum
| assessable
| uploaded
|
|-
| '''mod_forum\event\course_module_instance_list_viewed'''
| -
| mod_forum
| course_module_instance_list
| viewed
|
|-
| '''mod_forum\event\course_searched'''
| -
| mod_forum
| course
| searched
|
|-
| '''mod_forum\event\discussion_created'''
| -
| mod_forum
| discussion
| created
|
|-
| '''mod_forum\event\discussion_deleted'''
| -
| mod_forum
| discussion
| deleted
|
|-
| '''mod_forum\event\discussion_moved'''
| -
| mod_forum
| discussion
| moved
|
|-
| '''mod_forum\event\discussion_updated'''
| -
| mod_forum
| discussion
| updated
|
|-
| '''mod_forum\event\discussion_viewed'''
| -
| mod_forum
| discussion
| viewed
|
|-
| '''mod_forum\event\forum_viewed'''
| -
| mod_forum
| forum
| viewed
|
|-
| '''mod_forum\event\post_created'''
| -
| mod_forum
| post
| created
|
|-
| '''mod_forum\event\post_deleted'''
| -
| mod_forum
| post
| deleted
|
|-
| '''mod_forum\event\post_updated'''
| -
| mod_forum
| post
| updated
|
|-
| '''mod_forum\event\readtracking_disabled'''
| -
| mod_forum
| readtracking
| disabled
|
|-
| '''mod_forum\event\readtracking_enabled'''
| -
| mod_forum
| readtracking
| enabled
|
|-
| '''mod_forum\event\subscribers_viewed'''
| -
| mod_forum
| subscribers
| viewed
|
|-
| '''mod_forum\event\subscription_created'''
| -
| mod_forum
| subscription
| created
|
|-
| '''mod_forum\event\subscription_deleted'''
| -
| mod_forum
| subscription
| deleted
|
|-
| '''mod_forum\event\userreport_viewed'''
| -
| mod_forum
| userreport
| viewed
|
|-
| '''mod_glossary\event\comment_created'''
| -
| mod_glossary
| comment
| created
|
|-
| '''mod_glossary\event\comment_deleted'''
| -
| mod_glossary
| comment
| deleted
|
|-
| '''mod_lesson\event\course_module_instance_list_viewed'''
| -
| mod_lesson
| course_module_instance_list
| viewed
|
|-
| '''mod_lesson\event\course_module_viewed'''
| -
| mod_lesson
| course_module
| viewed
|
|-
| '''mod_lesson\event\essay_assessed'''
| -
| mod_lesson
| essay
| assessed
|
|-
| '''mod_lesson\event\essay_attempt_viewed'''
| -
| mod_lesson
| essay_attempt
| viewed
|
|-
| '''mod_lesson\event\highscore_added'''
| -
| mod_lesson
| highscore
| added
|
|-
| '''mod_lesson\event\highscores_viewed'''
| -
| mod_lesson
| highscores
| viewed
|
|-
| '''mod_lesson\event\lesson_ended'''
| -
| mod_lesson
| lesson
| ended
|
|-
| '''mod_lesson\event\lesson_started'''
| -
| mod_lesson
| lesson
| started
|
|-
| '''mod_lti\event\course_module_instance_list_viewed'''
| -
| mod_lti
| course_module_instance_list
| viewed
|
|-
| '''mod_lti\event\course_module_viewed'''
| -
| mod_lti
| course_module
| viewed
|
|-
| '''mod_lti\event\unknown_service_api_called'''
| lti_unknown_service_api_call
| mod_lti
| unknown_service_api
| called
|
|-
| '''mod_page\event\course_module_instance_list_viewed'''
| -
| mod_page
| course_module_instance_list
| viewed
|
|-
| '''mod_page\event\course_module_viewed'''
| -
| mod_page
| course_module
| viewed
|
|-
| '''mod_quiz\event\attempt_abandoned'''
| quiz_attempt_abandoned
| mod_quiz
| attempt
| abandoned
|
|-
| '''mod_quiz\event\attempt_becameoverdue'''
| quiz_attempt_overdue
| mod_quiz
| attempt
| becameoverdue
|
|-
| '''mod_quiz\event\attempt_started'''
| quiz_attempt_started
| mod_quiz
| attempt
| started
|
|-
| '''mod_quiz\event\attempt_submitted'''
| quiz_attempt_submitted
| mod_quiz
| attempt
| submitted
|
|-
| '''mod_resource\event\course_module_instance_list_viewed'''
| -
| mod_resource
| course_module_instance_list
| viewed
|
|-
| '''mod_resource\event\course_module_viewed'''
| -
| mod_resource
| course_module
| viewed
|
|-
| '''mod_scorm\event\attempt_deleted'''
| -
| mod_scorm
| attempt
| deleted
|
|-
| '''mod_scorm\event\course_module_instance_list_viewed'''
| -
| mod_scorm
| course_module_instance_list
| viewed
|
|-
| '''mod_scorm\event\course_module_viewed'''
| -
| mod_scorm
| course_module
| viewed
|
|-
| '''mod_scorm\event\interactions_viewed'''
| -
| mod_scorm
| interactions
| viewed
|
|-
| '''mod_scorm\event\report_viewed'''
| -
| mod_scorm
| report
| viewed
|
|-
| '''mod_scorm\event\sco_launched'''
| -
| mod_scorm
| sco
| launched
|
|-
| '''mod_scorm\event\tracks_viewed'''
| -
| mod_scorm
| tracks
| viewed
|
|-
| '''mod_scorm\event\user_report_viewed'''
| -
| mod_scorm
| user_report
| viewed
|
|-
| '''mod_url\event\course_module_instance_list_viewed'''
| -
| mod_url
| course_module_instance_list
| viewed
|
|-
| '''mod_url\event\course_module_viewed'''
| -
| mod_url
| course_module
| viewed
|
|-
| '''mod_wiki\event\comment_created'''
| -
| mod_wiki
| comment
| created
|
|-
| '''mod_wiki\event\comment_deleted'''
| -
| mod_wiki
| comment
| deleted
|
|-
| '''mod_wiki\event\comments_viewed'''
| -
| mod_wiki
| comments
| viewed
|
|-
| '''mod_wiki\event\course_module_instance_list_viewed'''
| -
| mod_wiki
| course_module_instance_list
| viewed
|
|-
| '''mod_wiki\event\course_module_viewed'''
| -
| mod_wiki
| course_module
| viewed
|
|-
| '''mod_wiki\event\page_created'''
| -
| mod_wiki
| page
| created
|
|-
| '''mod_wiki\event\page_deleted'''
| -
| mod_wiki
| page
| deleted
|
|-
| '''mod_wiki\event\page_diff_viewed'''
| -
| mod_wiki
| page_diff
| viewed
|
|-
| '''mod_wiki\event\page_history_viewed'''
| -
| mod_wiki
| page_history
| viewed
|
|-
| '''mod_wiki\event\page_locks_deleted'''
| -
| mod_wiki
| page_locks
| deleted
|
|-
| '''mod_wiki\event\page_map_viewed'''
| -
| mod_wiki
| page_map
| viewed
|
|-
| '''mod_wiki\event\page_updated'''
| -
| mod_wiki
| page
| updated
|
|-
| '''mod_wiki\event\page_version_deleted'''
| -
| mod_wiki
| page_version
| deleted
|
|-
| '''mod_wiki\event\page_version_restored'''
| -
| mod_wiki
| page_version
| restored
|
|-
| '''mod_wiki\event\page_version_viewed'''
| -
| mod_wiki
| page_version
| viewed
|
|-
| '''mod_wiki\event\page_viewed'''
| -
| mod_wiki
| page
| viewed
|
|-
| '''mod_workshop\event\assessable_uploaded'''
| assessable_content_uploaded
| mod_workshop
| assessable
| uploaded
|
|-
| '''mod_workshop\event\assessment_evaluated'''
| -
| mod_workshop
| assessment
| evaluated
|
|-
| '''mod_workshop\event\assessment_evaluations_reset'''
| -
| mod_workshop
| assessment_evaluations
| reset
|
|-
| '''mod_workshop\event\assessment_reevaluated'''
| -
| mod_workshop
| assessment
| reevaluated
|
|-
| '''mod_workshop\event\course_module_viewed'''
| workshop_viewed
| mod_workshop
| course_module
| viewed
|
|-
| '''mod_workshop\event\instances_list_viewed'''
| -
| mod_workshop
| instances_list
| viewed
|
|-
| '''mod_workshop\event\phase_switched'''
| -
| mod_workshop
| phase
| switched
|
|-
| '''mod_workshop\event\submission_assessed'''
| -
| mod_workshop
| submission
| assessed
|
|-
| '''mod_workshop\event\submission_created'''
| -
| mod_workshop
| submission
| created
|
|-
| '''mod_workshop\event\submission_reassessed'''
| -
| mod_workshop
| submission
| reassessed
|
|-
| '''mod_workshop\event\submission_updated'''
| -
| mod_workshop
| submission
| updated
|
|-
| '''mod_workshop\event\submission_viewed'''
| -
| mod_workshop
| submission
| viewed
|
|-
| '''report_log\event\content_viewed'''
| -
| report_log
| content
| viewed
|
|-
| '''report_loglive\event\content_viewed'''
| -
| report_loglive
| content
| viewed
|
|-
| '''report_outline\event\content_viewed'''
| -
| report_outline
| content
| viewed
|
|-
| '''report_participation\event\content_viewed'''
| -
| report_participation
| content
| viewed
|
|-
| '''report_stats\event\content_viewed'''
| -
| report_stats
| content
| viewed
|
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs can be added to this list if required, but additions should only be made if there is no valid alternative (we want to keep this list as small as possible).
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|abandoned
|When a attempt is abandoned by user (Quiz attempt)
|Moodle
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|assigned
| Assign some privilege or role to user.
|Moodle
|-
|attempted
| Trying to do an activity. Example: attempting a Math class.
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|becomeoverdue
| When an activity is overdue Example: Quiz attempt is overdue
|Moodle
|-
|called
| When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
|Used to represent "something new has been created".
|Moodle
|-
|deleted
|Used to indicate the object in context was deleted.
|Moodle
|-
|disabled
|When an activity is disabled. Example: forum read tracking disabled.
|Moodle
|-
|downloaded
|When a user download file from user. Example submission/report downloaded.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|enabled
|When some setting is enabled. Example: forum read tracking enabled.
|Moodle
|-
|ended
|When a process ends. Example: Lesson ended or course reset ended.
|Moodle
|-
|evaluated
|Material has been evaluated.
|Moodle
|-
|exported
|When a report is exported in certain format.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'. This is also used in case when message sending is failed.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|granted
|User is granted some extension or capability. Example: extension granted for submission.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|launched
|When an external object is launched. Try consider started if there is related stopped event.
|Moodle
|-
|locked
|When an activity is locked. Should have a related unlocked event.
|Moodle
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|printed
|Something is printed.
|Moodle
|-
|reassessed
|Submitted material has been assessed again.
|Moodle
|-
|reevaluated
|Material has been evaluated again.
|Moodle
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|reset
|Sets one or more properties back to the default value.
|Moodle
|-
|restored
|When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|revealed
|Some identity is revealed. Example: Identities revealed after blind marking.
|Moodle
|-
|searched
|Something is searched. Example: searched in course.
|Moodle
|-
|sent
|Message sent.
|Moodle
|-
|started
|Some activity started
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|unassigned
|As opposed to assigned. When some role is unassigned.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|uploaded
|When an assignment is uploaded.
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

==== Consistency among child events ====

If an event is extending a parent class, it should have the same exact name as the parent event.

=== Deprecated events ===
Following are the events that were supported in 2.5, but deprecated in 2.6 or later

groups_groupings_deleted (see MDL-41312)

groups_groupings_groups_removed (see MDL-41312)

groups_groups_deleted (see MDL-41312)

groups_members_removed (see MDL-41312)

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= PHP docs =
* All events php docs must include @since parameter, indicating when the event was first included in standard Moodle distribution.
* All events must declare the $other properties using mark down in the php docs. This later might be converted to a self documenting structure. (See MDL-45108)

<code php>
/**
* blog_association_created
*
* Class for event to be triggered when a new blog entry is associated with a context.
*
* @property-read array $other {
* Extra information about event.
*
* - string associatetype: type of blog association, course/coursemodule.
* - int blogid: id of blog.
* - int associateid: id of associate.
* - string subject: blog subject.
* }
*
* @package core
* @since Moodle 2.7
* @copyright 2013 onwards Ankit Agarwal
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Possible future work =
* MDL-45108 "Other" parameters should be defined in a method similar to webservices
* MDL-45217 Create traits for refactoring event triggers
* MDL-42897 Converting completion to use events
* MDL-42898 Develop a timeline page/block

= See Also =
[[Logging 2]]

[[Tin Can]]

YUI/Shifter

2014-09-22T20:48:53Z

Skodak: /* How do I load one of these modules from PHP code? */

{{Moodle 2.5}}
{{Moodle 2.6}}
{{Moodle 2.7}}

== What is Shifter and what does it do? ==

[http://yui.github.com/shifter Shifter] is a tool written by the YUI team to help ''build'' YUI modules.
It has been supported since Moodle 2.5 and we encourage its use.

It is written in JavaScript itself, and written as a [http://nodejs.org Node.JS] module which can be installed from [https://npmjs.org/package/shifter NPM].

Shifter takes your source JavaScript file(s), along with some meta-data, and wraps it all together into a built file. This file is known in YUI parlance as a '''module'''.
After building this file, Shifter then produces three versions:
* the file in its original form (DEBUG - '-debug' filename postfix);
* the DEBUG file with all debugging calls to Y.Log removed (RAW - no filename postfix); and
* the RAW file minified using [https://github.com/mishoo/UglifyJS UglifyJS] ('-min' filename postfix).

The meta-data file includes information on the module name, and its dependencies on other modules.

By separating out the actual JS code from its dependencies, we are able to take those dependencies and use them elsewhere in Moodle.
As an example, this dependency data can be used to inform the Loading system to reduce the number of HTTP requests with Combo Loading. This has a benefical effect upon performance.

Another feature of Shifter is its ability to handle ''rollups''. Rollups describe the inclusion of multiple YUI classes in the same module. This means that you can have different but related components all in the same module, but without having a single large and less-managable source file.

=== Why do I need build my modules? ===

Technically you don't, and you can continue to use the old data structure, but by doing so you can benefit from:
* reduced data sent over the wire due to minification - great for slower connections and mobile devices;
* reduced number of http queries - the separation of module meta-data means that it can be consumed and fed into the Loader allowing your module to use combo-loading;
* a slightly simplified JS syntax for your source files.

== Installing Shifter ==

Shifter is written in JavaScript and the [http://nodejs.org Node.JS] environment. You will need to install Node.JS first. This is usually fairly easy as there are pre-built binary packages for '''Windows and Mac OS'''.

After installing Node.JS you then use the Node NPM tool to install Shifter:
npm install shifter@0.4.6 -g

Note: At present, the supported version of Shifter for use in Moodle is version ''0.4.6''. You are not ''required'' to run a specific version of Shifter, but this is the version that Moodle YUI modules will be built with and you may find it beneficial to do so too.

For '''Ubuntu''' run:

sudo apt-get install npm
sudo apt-get install python-software-properties python g++ make
sudo apt-get update
sudo apt-get install nodejs
sudo ln -s /usr/bin/nodejs /usr/local/bin/node
sudo npm install shifter@0.4.6 -g

If you are behind a proxy, you will need to read http://jjasonclark.com/how-to-setup-node-behind-web-proxy.

== How do I write a YUI module which uses Shifter? ==

Easy - it's mostly just a case of building the right directory structure.

Assuming that you are creating a new YUI module in your block named fruit, and that your new YUI module will be called fruitbowl, we know the following:
{|
|Plugin type
|block
|-
|Plugin name
|fruit
|-
|Plugin frankenstyle name
|block_fruit
|-
|YUI Module name
|moodle-block_fruit-fruitbowl
|-
|}

This means that your Moodle plugin directory is:
/blocks/fruit

And your ''fruitbowl'' YUI module source will therefore be in:
/blocks/fruit/yui/src/fruitbowl

The overall module directory structure looks like this:
<code bash>
yui/
|-- src
|-- fruitbowl
|-- build.json
|-- js
| |-- fruitbowl.js
|-- meta
|-- fruitbowl.json
</code>

=== build.json ===

The ''build.json'' file defines the eventual modules which will be built, and the source files that you've written:

<code javascript>
{
"name": "moodle-block_fruit-fruitbowl",
"builds": {
"moodle-block_fruit-fruitbowl": {
"jsfiles": [
"fruitbowl.js"
]
}
}
}
</code>

=== meta/MODNAME.json ===

The ''meta/MODNAME.json'' file describes the list of dependencies for each module:

<code javascript>
{
"moodle-block_fruit-fruitbowl": {
"requires": [
"base",
"node"
]
}
}
</code>

=== js/MODNAME.js ===

The files in the js directory are the contents of your YUI module. This should include setting it up in the '''''M''''' namespace. As an example of a very basic structure:

<code javascript>
M.block_fruit = M.block_fruit || {};
M.block_fruit.fruitbowl = {
init: function() {
Y.one('#example').set('innerHTML', 'Example content');
}
};
</code>

=== Can I put two modules in one directory tree? ===

If you are still using Moodle 2.5, this does not work due to bug MDL-40478 (the non-default files cannot be loaded).

If you are using Moodle 2.6+ this is possible. It may sometimes be sensible if the modules are not independent, e.g. if one module will only ever be used by the other one rather than directly called from PHP, or another module.

If the modules are independent or might well be used separately from each other, then it is probably best to use a separate directory tree for each.

See examples in mod/scorm/yui/src and lib/yui/src/notification.

=== How do I load one of these modules from PHP code? ===

You need to run Shifter so that it generates the compiled code. See below.

Once you've done that, you can use PHP code like the following:

<code php>
$PAGE->requires->yui_module('moodle-block_fruit-fruitbowl', 'M.block_fruit.fruitbowl.init', array());
</code>

(The last empty array contains parameters for the init function, if required.)

== How do I use shifter? ==

So after writing out your structure, you now need to build it into a module. After installing Shifter, you have several options.

=== During development ===

A really nice way of running shifter during development is to have it detect changes to your files as you save them:

cd ~/git/moodle/blocks/fruit/yui/src
shifter --watch

The '''--watch''' option will watch for any changes to JS, JSON, CSS, or images within any module in the current directory and build that module when it detects changes.
''Note: There can be a short delay of a few seconds while the changes are discovered and the file is built''

This is great for development because you don't have to continously run shifter manually.

=== All YUI modules for the Moodle plugin you're currently working on ===

If you are working on several YUI modules at once, then you can have shifter build all of them at the same time:

cd ~/git/moodle/blocks/fruit/yui/src
shifter --walk

=== Just the module you're working on now ===
If you want to build just the module you're working on at the moment:

cd ~/git/moodle/blocks/fruit/yui/src
shifter --walk fruitbowl

Or:

cd ~/git/moodle/blocks/fruit/yui/src/fruitbowl
shifter

=== Across the whole of Moodle ===
If you want to build every YUI module in Moodle at once:

cd ~/git/moodle
shifter --walk --recursive

== Submitting my JavaScript back to Moodle core ==

If you're working on some JavaScript for Moodle core, either in the form of a bug fix or a new feature, then you probably want to know what to do with your built module.

'''We ask that you build your module and submit both the changes to tbe built module and the source directory.'''

In addition, the Continuous Integration server (Jenkins) will run ''shifter --walk --recursive'' on every run to ensure that all built files are up-to-date and correct.

If there are several commits to the same YUI module within a single period of Moodle integration, then the built files will conflict. In this case the integration team will manually build the module and resolve the conflict. If you are aware that there may be multiple changes to the same file, please indicate this when submitting your change for Integration Review. If you are familiar with the changes, you may wish to consider building the issues upon one another too.

== How do I convert my existing module? ==

If you already have an existing moodle YUI module and want to convert it to the new Shifter format, then it's pretty easy on the whole:

# create a new src/MODNAME directory;
# create js and meta directories within this;
# copy over your existing js file into the js directory;
# extract the meta-data;
# write your build.json;
# remove the YUI.add() wrapper from the top and bottom of your js file; and
# remove the old file.

To create the complete directory structure and copy your existing code into the right directory (steps 1 - 3):

mkdir -p src/MODNAME/{js,meta}
cp MODNAME/MODNAME.js src/MODNAME/js/

Refer to the section above on the correct contents of the build.json and meta/MODNAME.json files.

== Can I run my shifted module in older versions of Moodle 2 (before 2.5)? ==

We are aware that many developers wish to reduce the overhead of maintaining a plugin for multiple versions of Moodle and that using Shifter will make this much harder. Unfortunately you can't use the shifted version of your module directly, but you can run them in parallel by copying the built file into the old directory structure.

Moodle will always ''prefer'' the built shifted module over the older style module if both are present.

If doing this, we would recommend copying over the minified version of your file so that older versions of moodle benefit from your user of shifted code.

On a Linux-like operating system, you can use the following (again with our fruit example):
cp yui/build/moodle-mod_fruit-fruitbowl/moodle-mod_fruit-fruitbowl-min.js yui/fruitbowl/fruitbowl.js

Whilst developing, you may want to use a symlink so that you don't have to keep copying your changes after building them:
ln -s yui/build/moodle-mod_fruit-fruitbowl/moodle-mod_fruit-fruitbowl.js yui/fruitbowl/fruitbowl.js

==See also==

* [[JavaScript guidelines]]

Setting up PhpStorm

2014-07-01T23:46:19Z

Skodak: /* General settings */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===

You can optionally install latest Java JDK 1.7.x from [http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html Oracle] (Java 1.6 from Apple is not maintained much). By default PhpStorm uses only older 1.6.x java, but you can hack PhpStorm 7 to be compatible with Java 1.7 by editing the "PhpStorm.app/Contents/Info.plist" file, set JVMOptions - JVMVersion = 1.7*

==General settings==

* Disable missing @throws tag warning in "Preferences / Project Settings / Inspections / PHP / PHPDoc"
* Strip trailing whitespace from "Modified Lines" in "Preferences / IDE Settings / Editor"
* Show line numbers in "Preferences / IDE Settings / Editor / Appearance"

==Bug tracker integration==

* Add tracker linking in "Preferences / Version control / Issue Navigation"
* Set Issue ID to "MDL-\d+" and Issue link to "https://tracker.moodle.org/browse/$0"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Project Settings / Code Style / PHP" - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to Unix in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Moodle code checker==
TODO

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

Setting up PhpStorm

2014-07-01T23:44:06Z

Skodak: /* OS X */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===

You can optionally install latest Java JDK 1.7.x from [http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html Oracle] (Java 1.6 from Apple is not maintained much). By default PhpStorm uses only older 1.6.x java, but you can hack PhpStorm 7 to be compatible with Java 1.7 by editing the "PhpStorm.app/Contents/Info.plist" file, set JVMOptions - JVMVersion = 1.7*

==General settings==

* Disable missing @throws tag warning in "Preferences / Project Settings / Inspections / PHP / PHPDoc"
* Strip trailing whitespace from "Modified Lines" in "Preferences / IDE Settings / Editor"
* Show line numbers in "Preferences / IDE Settings / Editor / Appearance"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Project Settings / Code Style / PHP" - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to Unix in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Moodle code checker==
TODO

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

PHPUnit integration

2014-06-19T21:52:43Z

Skodak: /* Class and file naming rules */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

==Class and file naming rules==
The class names of all testcases need to be unique, Frankenstyle prefix is used to guarantee this. Since 2.6 it is possible to use automatic class loader when executing individual unit tests.

* All test case classes start with Frankenstyle prefix, for example: '''mod_forum_''', '''block_html_''', '''core_'''.
* All test case classes end with '''_testcase''' suffix.
* File names are constructed from the class names - the Frankenstyle prefix is removed, suffix '''_testcase''' is replaced with '''_test'''

Example:
* class '''mod_forum_lib_testcase''' is expected in file '''/mod/forum/tests/lib_test.php''', executed as <code>vendor/bin/phpunit mod_forum_lib_testcase</code>
* class '''core_text_testcase''' is expected in file '''/lib/texts/text_test.php''', executed as <code>vendor/bin/phpunit core_text_testcase</code>

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests. The expected file name for this test case is '''/mod/myplugin/tests/sample_basic_test.php'''.

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

The expected file name for this test case is '''/mod/myplugin/tests/some_permission_test.php'''.

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

PHPUnit integration

2014-06-19T21:51:59Z

Skodak: /* Class and file naming rules */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

==Class and file naming rules==
The class names of all testcases need to be unique, Frankenstyle prefix is used to guarantee this. Since 2.7 it is possible to use automatic class loader when executing individual unit tests.

* All test case classes start with Frankenstyle prefix, for example: '''mod_forum_''', '''block_html_''', '''core_'''.
* All test case classes end with '''_testcase''' suffix.
* File names are constructed from the class names - the Frankenstyle prefix is removed, suffix '''_testcase''' is replaced with '''_test'''

Example:
* class '''mod_forum_lib_testcase''' is expected in file '''/mod/forum/tests/lib_test.php''', executed as <code>vendor/bin/phpunit mod_forum_lib_testcase</code>
* class '''core_text_testcase''' is expected in file '''/lib/texts/text_test.php''', executed as <code>vendor/bin/phpunit core_text_testcase</code>

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests. The expected file name for this test case is '''/mod/myplugin/tests/sample_basic_test.php'''.

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

The expected file name for this test case is '''/mod/myplugin/tests/some_permission_test.php'''.

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

Setting up PhpStorm

2014-06-19T00:20:08Z

Skodak: /* Code formatting */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===
Install latest Java JDK 1.7.x from [http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html Oracle] (Java 1.6 from Apple is not maintained much).

You can hack older PhpStorm 7 to be compatible with Java 1.7 by editing the "PhpStorm.app/Contents/Info.plist" file, set JVMOptions - JVMVersion = 1.7*

==General settings==

* Disable missing @throws tag warning in "Preferences / Project Settings / Inspections / PHP / PHPDoc"
* Strip trailing whitespace from "Modified Lines" in "Preferences / IDE Settings / Editor"
* Show line numbers in "Preferences / IDE Settings / Editor / Appearance"

==Code formatting==

* Setup coding style to use all rules from [[Coding style]] in "Preferences / Project Settings / Code Style / PHP" - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste.
* Set line separator to Unix in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Moodle code checker==
TODO

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

Setting up Netbeans

2014-06-19T00:14:57Z

Skodak: /* PHPUnit support */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest stable version from http://netbeans.org. Get the bundle that contains only PHP support.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[:en:CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will need to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


=== Wiki page needs updating ===

Git is now integrated into Netbeans 7
https://netbeans.org/kb/70/ide/git.html

== Optimization ==

=== Sun JDK ===
1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

=== ScanOnDemand ===
To prevent NetBeans from scanning the whole code with every start up you can use the following plug-in: http://wiki.netbeans.org/ScanOnDemand

== Coding faster ==

=== Coding standards ===

* There is NB config file available with the [https://github.com/enovation/moodle-utils/tree/master/netbeans-config Moodle coding settings]

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://netbeans.org/kb/docs/php/phpunit.html Netbeans PHPUnit support].

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within NetBeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to ''Tools->plugins->available plugins'' and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer tools|NetBeans]]

PHPUnit

2014-06-19T00:13:05Z

Skodak: /* PHPUnit support in IDEs */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Please note the path name is optional if the testcase class and file names are standardised as described in [[Writing PHPUnit tests]].

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [[Setting up Eclipse]]
* [[Setting up Netbeans]]
* [[Setting up PhpStorm]]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

[[Category:Unit testing]]

Writing PHPUnit tests

2014-06-19T00:07:00Z

Skodak: /* Sample plugin testcase */

{{Moodle 2.3}}

Moodle PHPUnit integration is designed to allow easy adding of new tests. At the start of each test the state is automatically reset to fresh new installation (unless explicitly told not to reset).

=Testcase classes=

There are two basic test class that are supposed to used in all Moodle unit tests - basic_testcase and advanced_testcase. '''Please note it is strongly recommended to put only one testcase into each class file.'''
;basic_testcase : Very simple tests that do not modify database, dataroot or any PHP globals. It can be used for example when trying examples from the official PHPUnit tutorial.
;advanced_testcase : Enhanced testcase class enhanced for easy testing of Moodle code.

There is a third testcase class that is specially designed for testing of our Moodle database layer, it should not be used for other purposes.

== Assertions ==

The complete list of assertions can be found in the [http://www.phpunit.de/manual/3.7/en/appendixes.assertions.html phpunit manual].
==Sample plugin testcase==

PHPUnit tests are located in <code>tests/*_test.php</code> files in your plugin, for example mod/myplugin/tests/sample_test.php, the file should contain only one class that extends <code>advanced_testcase</code>:

<code php>
class mod_myplugin_sample_testcase extends advanced_testcase {
public function test_adding() {
$this->assertEquals(2, 1+2);
}
}
</code>

See [[PHPUnit integration#Class and file naming rules]] for more information.

==Inclusion of Moodle library files==

If you want to include some Moodle library files you should always declare '''global $CFG'''. The reason is that testcase files may be included from non-moodle code which does not make the global $CFG available automatically.

==Automatic state reset==
By default after each test Moodle database and dataroot is automatically reset to the original state which was present right after installation. make sure to use $this->resetAfterTest() to indicate that the database or changes of standard global variables are expected.

<code php>
class mod_myplugin_testcase extends advanced_testcase {
public function test_deleting() {
global $DB;
$this->resetAfterTest(true);
$DB->delete_records('user');
$this->assertEmpty($DB->get_records('user'));
}
public function test_user_table_was_reset() {
global $DB;
$this->assertEquals(2, $DB->count_records('user', array()));
}
}
</code>

=Generators=

Tests that need to modify default installation may use generators to create new courses, users, etc. All examples on this page should be used from test methods of a test class derived from advanced_testcase.

Note if you are using PHPUnit @dataProvider functions to provide parameters to unit tests, you can not use the data generator or change the user etc in the data provider function.

==Creating users==
At the start of each test there are only two users present - guest and administrator. If you need to add more test accounts use:
<code php>
$user = $this->getDataGenerator()->create_user();
</code>

You may also specify properties of the user account, for example:
<code php>
$user1 = $this->getDataGenerator()->create_user(array('email'=>'user1@example.com', 'username'=>'user1'));
</code>

By default no user is logged-in, use setUser() method to change current $USER value:
<code php>
$this->setUser($user1);
</code>

Guest and admin accounts have a shortcut methods:
<code php>
$this->setGuestUser();
$this->setAdminUser();
</code>

Null can be used to set current user back to not-logged-in:
<code php>
$this->setUser(null);
</code>

==Creating course categories==

<code php>
$category1 = $this->getDataGenerator()->create_category();
$category2 = $this->getDataGenerator()->create_category(array('name'=>'Some subcategory', 'parent'=>$category1->id));
</code>

==Creating courses==

<code php>
$course1 = $this->getDataGenerator()->create_course();

$category = $this->getDataGenerator()->create_category();
$course2 = $this->getDataGenerator()->create_course(array('name'=>'Some course', 'category'=>$category->id));
</code>

==Creating activities==

Some activity plugins include instance generators. The generator class are defined in plugindirectory/tests/generator/lib.php.

Example of creation of new course with one page resource:

<code php>
$course = $this->getDataGenerator()->create_course();
$generator = $this->getDataGenerator()->get_plugin_generator('mod_page');
$generator->create_instance(array('course'=>$course->id));
</code>

==Creating cohorts==
{{Moodle 2.4}}
Since 2.4 there the data generator supports creation of new cohorts.

<code php>
$cohort = $this->getDataGenerator()->create_cohort();
</code>

==Simplified user enrolments==
{{Moodle 2.4}}
Instead of standard enrolment API it is possible to use simplified method in data generator. It is intended to be used with self and manual enrolment plugins.

<code php>
$this->getDataGenerator()->enrol_user($userid, $courseid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid, 'manual');
</code>

==Other types of plugin==
{{Moodle 2.5}}
Any other type of plugin can have a generator. The generator class should extend component_generator_base, and then you can get an instance using $mygenerator = $this->getDataGenerator()->get_plugin_generator($frankenstylecomponentname);

For some types of plugin, like mod documented above, there may be a more specific class than component_generator_base to extend, like testing_module_generator. That will give a consistent set of method names to use. Otherwise, you can create whatever methods you like on your generator, to create the different things you need to work whith.

=Long tests=

All standard test should execute as fast as possible. Tests that take a loner time to execute (>10s) or are otherwise expensive (such as querying external servers that might be flooded by all dev machines) should be execute only when PHPUNIT_LONGTEST is true. This constant can be set in phpunit.xml or directly in config.php.

=Large test data=
See advanced_testcase::createXMLDataSet() and advanced_testcase::createCsvDataSet() and related functions there for easier ways to manage large test data sets within files rather than arrays in code. See [[PHPUnit_integration#Extra_methods]]

=Testing sending of messages=
{{Moodle 2.4}}
You can temporarily redirect all messages sent via message_send() to a message sink object. This allows developers to verify that the tested code is sending expected messages.

To test code using messaging first disable the use of transactions and then redirect the messaging into a new message sink, you can inspect the results later.
<code php>
$this->preventResetByRollback();
$sink = $this->redirectMessages();
//... code that is sending messages
$messages = $sink->get_messages();
$this->assertEquals(3, count($messages));
//.. test messages were generated in correct order with appropriate content
</code>

=Testing sending of emails=
{{Moodle 2.6}}
You can temporarily redirect emails sent via email_to_user() to a email message sink object. This allows developers to verify that the tested code is sending expected emails.

To test code using messaging first unset 'noemailever' setting and then redirect the emails into a new message sink where you can inspect the results later.
<code php>
unset_config('noemailever');
$sink = $this->redirectEmails();
//... code that is sending email
$messages = $sink->get_messages();
$this->assertEquals(1, count($messages));
</code>

=Extra test settings=

Usually the test should not interact with any external systems and it should work the same on all systems. But sometimes you need to specify some option for connection to external systems or system configuration. It is intentionally not possible to use $CFG settings from config.php.

There are several ways how to inject your custom settings:
* define test setting constants in your phpunit.xml file
* define test setting constants in your config.php

These constants may be then used in your test or plugin code.

=See also=
* [[PHPUnit integration]]
* [[PHPUnit]]

[[Category:Unit testing]]

Writing PHPUnit tests

2014-06-19T00:05:38Z

Skodak: /* Sample plugin testcase */

{{Moodle 2.3}}

Moodle PHPUnit integration is designed to allow easy adding of new tests. At the start of each test the state is automatically reset to fresh new installation (unless explicitly told not to reset).

=Testcase classes=

There are two basic test class that are supposed to used in all Moodle unit tests - basic_testcase and advanced_testcase. '''Please note it is strongly recommended to put only one testcase into each class file.'''
;basic_testcase : Very simple tests that do not modify database, dataroot or any PHP globals. It can be used for example when trying examples from the official PHPUnit tutorial.
;advanced_testcase : Enhanced testcase class enhanced for easy testing of Moodle code.

There is a third testcase class that is specially designed for testing of our Moodle database layer, it should not be used for other purposes.

== Assertions ==

The complete list of assertions can be found in the [http://www.phpunit.de/manual/3.7/en/appendixes.assertions.html phpunit manual].
==Sample plugin testcase==

PHPUnit tests are located in <code>tests/*_test.php</code> files in your plugin, for example mod/myplugin/tests/sample_test.php, the file should contain only one class that extends <code>advanced_testcase</code>:

<code php>
class mod_myplugin_sample_testcase extends advanced_testcase {
public function test_adding() {
$this->assertEquals(2, 1+2);
}
}
</code>

See Class and file naming rules section in [[PHPUnit integration]] for more information about naming of test case classes and files.

==Inclusion of Moodle library files==

If you want to include some Moodle library files you should always declare '''global $CFG'''. The reason is that testcase files may be included from non-moodle code which does not make the global $CFG available automatically.

==Automatic state reset==
By default after each test Moodle database and dataroot is automatically reset to the original state which was present right after installation. make sure to use $this->resetAfterTest() to indicate that the database or changes of standard global variables are expected.

<code php>
class mod_myplugin_testcase extends advanced_testcase {
public function test_deleting() {
global $DB;
$this->resetAfterTest(true);
$DB->delete_records('user');
$this->assertEmpty($DB->get_records('user'));
}
public function test_user_table_was_reset() {
global $DB;
$this->assertEquals(2, $DB->count_records('user', array()));
}
}
</code>

=Generators=

Tests that need to modify default installation may use generators to create new courses, users, etc. All examples on this page should be used from test methods of a test class derived from advanced_testcase.

Note if you are using PHPUnit @dataProvider functions to provide parameters to unit tests, you can not use the data generator or change the user etc in the data provider function.

==Creating users==
At the start of each test there are only two users present - guest and administrator. If you need to add more test accounts use:
<code php>
$user = $this->getDataGenerator()->create_user();
</code>

You may also specify properties of the user account, for example:
<code php>
$user1 = $this->getDataGenerator()->create_user(array('email'=>'user1@example.com', 'username'=>'user1'));
</code>

By default no user is logged-in, use setUser() method to change current $USER value:
<code php>
$this->setUser($user1);
</code>

Guest and admin accounts have a shortcut methods:
<code php>
$this->setGuestUser();
$this->setAdminUser();
</code>

Null can be used to set current user back to not-logged-in:
<code php>
$this->setUser(null);
</code>

==Creating course categories==

<code php>
$category1 = $this->getDataGenerator()->create_category();
$category2 = $this->getDataGenerator()->create_category(array('name'=>'Some subcategory', 'parent'=>$category1->id));
</code>

==Creating courses==

<code php>
$course1 = $this->getDataGenerator()->create_course();

$category = $this->getDataGenerator()->create_category();
$course2 = $this->getDataGenerator()->create_course(array('name'=>'Some course', 'category'=>$category->id));
</code>

==Creating activities==

Some activity plugins include instance generators. The generator class are defined in plugindirectory/tests/generator/lib.php.

Example of creation of new course with one page resource:

<code php>
$course = $this->getDataGenerator()->create_course();
$generator = $this->getDataGenerator()->get_plugin_generator('mod_page');
$generator->create_instance(array('course'=>$course->id));
</code>

==Creating cohorts==
{{Moodle 2.4}}
Since 2.4 there the data generator supports creation of new cohorts.

<code php>
$cohort = $this->getDataGenerator()->create_cohort();
</code>

==Simplified user enrolments==
{{Moodle 2.4}}
Instead of standard enrolment API it is possible to use simplified method in data generator. It is intended to be used with self and manual enrolment plugins.

<code php>
$this->getDataGenerator()->enrol_user($userid, $courseid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid, 'manual');
</code>

==Other types of plugin==
{{Moodle 2.5}}
Any other type of plugin can have a generator. The generator class should extend component_generator_base, and then you can get an instance using $mygenerator = $this->getDataGenerator()->get_plugin_generator($frankenstylecomponentname);

For some types of plugin, like mod documented above, there may be a more specific class than component_generator_base to extend, like testing_module_generator. That will give a consistent set of method names to use. Otherwise, you can create whatever methods you like on your generator, to create the different things you need to work whith.

=Long tests=

All standard test should execute as fast as possible. Tests that take a loner time to execute (>10s) or are otherwise expensive (such as querying external servers that might be flooded by all dev machines) should be execute only when PHPUNIT_LONGTEST is true. This constant can be set in phpunit.xml or directly in config.php.

=Large test data=
See advanced_testcase::createXMLDataSet() and advanced_testcase::createCsvDataSet() and related functions there for easier ways to manage large test data sets within files rather than arrays in code. See [[PHPUnit_integration#Extra_methods]]

=Testing sending of messages=
{{Moodle 2.4}}
You can temporarily redirect all messages sent via message_send() to a message sink object. This allows developers to verify that the tested code is sending expected messages.

To test code using messaging first disable the use of transactions and then redirect the messaging into a new message sink, you can inspect the results later.
<code php>
$this->preventResetByRollback();
$sink = $this->redirectMessages();
//... code that is sending messages
$messages = $sink->get_messages();
$this->assertEquals(3, count($messages));
//.. test messages were generated in correct order with appropriate content
</code>

=Testing sending of emails=
{{Moodle 2.6}}
You can temporarily redirect emails sent via email_to_user() to a email message sink object. This allows developers to verify that the tested code is sending expected emails.

To test code using messaging first unset 'noemailever' setting and then redirect the emails into a new message sink where you can inspect the results later.
<code php>
unset_config('noemailever');
$sink = $this->redirectEmails();
//... code that is sending email
$messages = $sink->get_messages();
$this->assertEquals(1, count($messages));
</code>

=Extra test settings=

Usually the test should not interact with any external systems and it should work the same on all systems. But sometimes you need to specify some option for connection to external systems or system configuration. It is intentionally not possible to use $CFG settings from config.php.

There are several ways how to inject your custom settings:
* define test setting constants in your phpunit.xml file
* define test setting constants in your config.php

These constants may be then used in your test or plugin code.

=See also=
* [[PHPUnit integration]]
* [[PHPUnit]]

[[Category:Unit testing]]

Writing PHPUnit tests

2014-06-19T00:04:51Z

Skodak: /* Sample plugin testcase */

{{Moodle 2.3}}

Moodle PHPUnit integration is designed to allow easy adding of new tests. At the start of each test the state is automatically reset to fresh new installation (unless explicitly told not to reset).

=Testcase classes=

There are two basic test class that are supposed to used in all Moodle unit tests - basic_testcase and advanced_testcase. '''Please note it is strongly recommended to put only one testcase into each class file.'''
;basic_testcase : Very simple tests that do not modify database, dataroot or any PHP globals. It can be used for example when trying examples from the official PHPUnit tutorial.
;advanced_testcase : Enhanced testcase class enhanced for easy testing of Moodle code.

There is a third testcase class that is specially designed for testing of our Moodle database layer, it should not be used for other purposes.

== Assertions ==

The complete list of assertions can be found in the [http://www.phpunit.de/manual/3.7/en/appendixes.assertions.html phpunit manual].
==Sample plugin testcase==

PHPUnit tests are located in <code>tests/*_test.php</code> files in your plugin, for example mod/myplugin/tests/sample_test.php, the file should contain only one class that extends <code>advanced_testcase</code>:

<code php>
class mod_myplugin_sample_testcase extends advanced_testcase {
public function test_adding() {
$this->assertEquals(2, 1+2);
}
}
</code>

See Class and file naming rules section in [[PHPUnit Integration]] for more information about naming of test case classes and files.

==Inclusion of Moodle library files==

If you want to include some Moodle library files you should always declare '''global $CFG'''. The reason is that testcase files may be included from non-moodle code which does not make the global $CFG available automatically.

==Automatic state reset==
By default after each test Moodle database and dataroot is automatically reset to the original state which was present right after installation. make sure to use $this->resetAfterTest() to indicate that the database or changes of standard global variables are expected.

<code php>
class mod_myplugin_testcase extends advanced_testcase {
public function test_deleting() {
global $DB;
$this->resetAfterTest(true);
$DB->delete_records('user');
$this->assertEmpty($DB->get_records('user'));
}
public function test_user_table_was_reset() {
global $DB;
$this->assertEquals(2, $DB->count_records('user', array()));
}
}
</code>

=Generators=

Tests that need to modify default installation may use generators to create new courses, users, etc. All examples on this page should be used from test methods of a test class derived from advanced_testcase.

Note if you are using PHPUnit @dataProvider functions to provide parameters to unit tests, you can not use the data generator or change the user etc in the data provider function.

==Creating users==
At the start of each test there are only two users present - guest and administrator. If you need to add more test accounts use:
<code php>
$user = $this->getDataGenerator()->create_user();
</code>

You may also specify properties of the user account, for example:
<code php>
$user1 = $this->getDataGenerator()->create_user(array('email'=>'user1@example.com', 'username'=>'user1'));
</code>

By default no user is logged-in, use setUser() method to change current $USER value:
<code php>
$this->setUser($user1);
</code>

Guest and admin accounts have a shortcut methods:
<code php>
$this->setGuestUser();
$this->setAdminUser();
</code>

Null can be used to set current user back to not-logged-in:
<code php>
$this->setUser(null);
</code>

==Creating course categories==

<code php>
$category1 = $this->getDataGenerator()->create_category();
$category2 = $this->getDataGenerator()->create_category(array('name'=>'Some subcategory', 'parent'=>$category1->id));
</code>

==Creating courses==

<code php>
$course1 = $this->getDataGenerator()->create_course();

$category = $this->getDataGenerator()->create_category();
$course2 = $this->getDataGenerator()->create_course(array('name'=>'Some course', 'category'=>$category->id));
</code>

==Creating activities==

Some activity plugins include instance generators. The generator class are defined in plugindirectory/tests/generator/lib.php.

Example of creation of new course with one page resource:

<code php>
$course = $this->getDataGenerator()->create_course();
$generator = $this->getDataGenerator()->get_plugin_generator('mod_page');
$generator->create_instance(array('course'=>$course->id));
</code>

==Creating cohorts==
{{Moodle 2.4}}
Since 2.4 there the data generator supports creation of new cohorts.

<code php>
$cohort = $this->getDataGenerator()->create_cohort();
</code>

==Simplified user enrolments==
{{Moodle 2.4}}
Instead of standard enrolment API it is possible to use simplified method in data generator. It is intended to be used with self and manual enrolment plugins.

<code php>
$this->getDataGenerator()->enrol_user($userid, $courseid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid, 'manual');
</code>

==Other types of plugin==
{{Moodle 2.5}}
Any other type of plugin can have a generator. The generator class should extend component_generator_base, and then you can get an instance using $mygenerator = $this->getDataGenerator()->get_plugin_generator($frankenstylecomponentname);

For some types of plugin, like mod documented above, there may be a more specific class than component_generator_base to extend, like testing_module_generator. That will give a consistent set of method names to use. Otherwise, you can create whatever methods you like on your generator, to create the different things you need to work whith.

=Long tests=

All standard test should execute as fast as possible. Tests that take a loner time to execute (>10s) or are otherwise expensive (such as querying external servers that might be flooded by all dev machines) should be execute only when PHPUNIT_LONGTEST is true. This constant can be set in phpunit.xml or directly in config.php.

=Large test data=
See advanced_testcase::createXMLDataSet() and advanced_testcase::createCsvDataSet() and related functions there for easier ways to manage large test data sets within files rather than arrays in code. See [[PHPUnit_integration#Extra_methods]]

=Testing sending of messages=
{{Moodle 2.4}}
You can temporarily redirect all messages sent via message_send() to a message sink object. This allows developers to verify that the tested code is sending expected messages.

To test code using messaging first disable the use of transactions and then redirect the messaging into a new message sink, you can inspect the results later.
<code php>
$this->preventResetByRollback();
$sink = $this->redirectMessages();
//... code that is sending messages
$messages = $sink->get_messages();
$this->assertEquals(3, count($messages));
//.. test messages were generated in correct order with appropriate content
</code>

=Testing sending of emails=
{{Moodle 2.6}}
You can temporarily redirect emails sent via email_to_user() to a email message sink object. This allows developers to verify that the tested code is sending expected emails.

To test code using messaging first unset 'noemailever' setting and then redirect the emails into a new message sink where you can inspect the results later.
<code php>
unset_config('noemailever');
$sink = $this->redirectEmails();
//... code that is sending email
$messages = $sink->get_messages();
$this->assertEquals(1, count($messages));
</code>

=Extra test settings=

Usually the test should not interact with any external systems and it should work the same on all systems. But sometimes you need to specify some option for connection to external systems or system configuration. It is intentionally not possible to use $CFG settings from config.php.

There are several ways how to inject your custom settings:
* define test setting constants in your phpunit.xml file
* define test setting constants in your config.php

These constants may be then used in your test or plugin code.

=See also=
* [[PHPUnit integration]]
* [[PHPUnit]]

[[Category:Unit testing]]

Writing PHPUnit tests

2014-06-19T00:03:48Z

Skodak: /* Sample plugin testcase */

{{Moodle 2.3}}

Moodle PHPUnit integration is designed to allow easy adding of new tests. At the start of each test the state is automatically reset to fresh new installation (unless explicitly told not to reset).

=Testcase classes=

There are two basic test class that are supposed to used in all Moodle unit tests - basic_testcase and advanced_testcase. '''Please note it is strongly recommended to put only one testcase into each class file.'''
;basic_testcase : Very simple tests that do not modify database, dataroot or any PHP globals. It can be used for example when trying examples from the official PHPUnit tutorial.
;advanced_testcase : Enhanced testcase class enhanced for easy testing of Moodle code.

There is a third testcase class that is specially designed for testing of our Moodle database layer, it should not be used for other purposes.

== Assertions ==

The complete list of assertions can be found in the [http://www.phpunit.de/manual/3.7/en/appendixes.assertions.html phpunit manual].
==Sample plugin testcase==

PHPUnit tests are located in <code>tests/*_test.php</code> files in your plugin, for example mod/myplugin/tests/sample_test.php, the file should contain only one class that extends <code>advanced_testcase</code>:

<code php>
class mod_myplugin_sample_testcase extends advanced_testcase {
public function test_adding() {
$this->assertEquals(2, 1+2);
}
}
</code>

See [[#Class and file naming rules|PHPUnit Integration]] for more information about naming of test case classes and files.

==Inclusion of Moodle library files==

If you want to include some Moodle library files you should always declare '''global $CFG'''. The reason is that testcase files may be included from non-moodle code which does not make the global $CFG available automatically.

==Automatic state reset==
By default after each test Moodle database and dataroot is automatically reset to the original state which was present right after installation. make sure to use $this->resetAfterTest() to indicate that the database or changes of standard global variables are expected.

<code php>
class mod_myplugin_testcase extends advanced_testcase {
public function test_deleting() {
global $DB;
$this->resetAfterTest(true);
$DB->delete_records('user');
$this->assertEmpty($DB->get_records('user'));
}
public function test_user_table_was_reset() {
global $DB;
$this->assertEquals(2, $DB->count_records('user', array()));
}
}
</code>

=Generators=

Tests that need to modify default installation may use generators to create new courses, users, etc. All examples on this page should be used from test methods of a test class derived from advanced_testcase.

Note if you are using PHPUnit @dataProvider functions to provide parameters to unit tests, you can not use the data generator or change the user etc in the data provider function.

==Creating users==
At the start of each test there are only two users present - guest and administrator. If you need to add more test accounts use:
<code php>
$user = $this->getDataGenerator()->create_user();
</code>

You may also specify properties of the user account, for example:
<code php>
$user1 = $this->getDataGenerator()->create_user(array('email'=>'user1@example.com', 'username'=>'user1'));
</code>

By default no user is logged-in, use setUser() method to change current $USER value:
<code php>
$this->setUser($user1);
</code>

Guest and admin accounts have a shortcut methods:
<code php>
$this->setGuestUser();
$this->setAdminUser();
</code>

Null can be used to set current user back to not-logged-in:
<code php>
$this->setUser(null);
</code>

==Creating course categories==

<code php>
$category1 = $this->getDataGenerator()->create_category();
$category2 = $this->getDataGenerator()->create_category(array('name'=>'Some subcategory', 'parent'=>$category1->id));
</code>

==Creating courses==

<code php>
$course1 = $this->getDataGenerator()->create_course();

$category = $this->getDataGenerator()->create_category();
$course2 = $this->getDataGenerator()->create_course(array('name'=>'Some course', 'category'=>$category->id));
</code>

==Creating activities==

Some activity plugins include instance generators. The generator class are defined in plugindirectory/tests/generator/lib.php.

Example of creation of new course with one page resource:

<code php>
$course = $this->getDataGenerator()->create_course();
$generator = $this->getDataGenerator()->get_plugin_generator('mod_page');
$generator->create_instance(array('course'=>$course->id));
</code>

==Creating cohorts==
{{Moodle 2.4}}
Since 2.4 there the data generator supports creation of new cohorts.

<code php>
$cohort = $this->getDataGenerator()->create_cohort();
</code>

==Simplified user enrolments==
{{Moodle 2.4}}
Instead of standard enrolment API it is possible to use simplified method in data generator. It is intended to be used with self and manual enrolment plugins.

<code php>
$this->getDataGenerator()->enrol_user($userid, $courseid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid, 'manual');
</code>

==Other types of plugin==
{{Moodle 2.5}}
Any other type of plugin can have a generator. The generator class should extend component_generator_base, and then you can get an instance using $mygenerator = $this->getDataGenerator()->get_plugin_generator($frankenstylecomponentname);

For some types of plugin, like mod documented above, there may be a more specific class than component_generator_base to extend, like testing_module_generator. That will give a consistent set of method names to use. Otherwise, you can create whatever methods you like on your generator, to create the different things you need to work whith.

=Long tests=

All standard test should execute as fast as possible. Tests that take a loner time to execute (>10s) or are otherwise expensive (such as querying external servers that might be flooded by all dev machines) should be execute only when PHPUNIT_LONGTEST is true. This constant can be set in phpunit.xml or directly in config.php.

=Large test data=
See advanced_testcase::createXMLDataSet() and advanced_testcase::createCsvDataSet() and related functions there for easier ways to manage large test data sets within files rather than arrays in code. See [[PHPUnit_integration#Extra_methods]]

=Testing sending of messages=
{{Moodle 2.4}}
You can temporarily redirect all messages sent via message_send() to a message sink object. This allows developers to verify that the tested code is sending expected messages.

To test code using messaging first disable the use of transactions and then redirect the messaging into a new message sink, you can inspect the results later.
<code php>
$this->preventResetByRollback();
$sink = $this->redirectMessages();
//... code that is sending messages
$messages = $sink->get_messages();
$this->assertEquals(3, count($messages));
//.. test messages were generated in correct order with appropriate content
</code>

=Testing sending of emails=
{{Moodle 2.6}}
You can temporarily redirect emails sent via email_to_user() to a email message sink object. This allows developers to verify that the tested code is sending expected emails.

To test code using messaging first unset 'noemailever' setting and then redirect the emails into a new message sink where you can inspect the results later.
<code php>
unset_config('noemailever');
$sink = $this->redirectEmails();
//... code that is sending email
$messages = $sink->get_messages();
$this->assertEquals(1, count($messages));
</code>

=Extra test settings=

Usually the test should not interact with any external systems and it should work the same on all systems. But sometimes you need to specify some option for connection to external systems or system configuration. It is intentionally not possible to use $CFG settings from config.php.

There are several ways how to inject your custom settings:
* define test setting constants in your phpunit.xml file
* define test setting constants in your config.php

These constants may be then used in your test or plugin code.

=See also=
* [[PHPUnit integration]]
* [[PHPUnit]]

[[Category:Unit testing]]

PHPUnit integration

2014-06-18T23:59:58Z

Skodak: /* Class and file naming rules */

PHPUnit integration

2014-06-18T23:59:35Z

Skodak: /* Organisation of test files */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

==Class and file naming rules==
The class names of all testcases need to be unique, Frankenstyle prefix is used to guarantee this. Since 2.6 it is possible to use automatic class loader when executing individual unit tests.

* All test case classes start with Frankenstyle prefix, for example: '''mod_forum_''', '''block_html_''', '''core_'''.
* All test case classes end with '''_testcase' suffix.
* File names are constructed from the class names - the Frankenstyle prefix is removed, suffix '''_testcase''' is replaced with '''_test'''

Example:
* class '''mod_forum_lib_testcase''' is expected in file '''/mod/forum/tests/lib_test.php''', executed as <code>vendor/bin/phpunit mod_forum_lib_testcase</code>
* class '''core_text_testcase''' is expected in file '''/lib/texts/text_test.php''', executed as <code>vendor/bin/phpunit core_text_testcase</code>

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests. The expected file name for this test case is '''/mod/myplugin/tests/sample_basic_test.php'''.

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

The expected file name for this test case is '''/mod/myplugin/tests/some_permission_test.php'''.

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

PHPUnit integration

2014-06-18T23:51:26Z

Skodak: /* advanced_testcase */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests. The expected file name for this test case is '''/mod/myplugin/tests/sample_basic_test.php'''.

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

The expected file name for this test case is '''/mod/myplugin/tests/some_permission_test.php'''.

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

PHPUnit integration

2014-06-18T23:50:52Z

Skodak: /* basic_testcase */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests. The expected file name for this test case is '''/mod/myplugin/tests/sample_basic_test.php'''.

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

PHPUnit

2014-06-18T23:49:20Z

Skodak: /* Running a single test quickly */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Please note the path name is optional if the testcase class and file names are standardised as described in [[Writing PHPUnit tests]].

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

[[Category:Unit testing]]

PHPUnit

2014-06-18T23:48:39Z

Skodak: /* Running a single test quickly */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

Please note the path name is optional if the testcase class and file names are standardised as described in [[Writing PHPUnit tests]]

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

[[Category:Unit testing]]

PHPUnit integration

2014-06-18T23:48:07Z

Skodak: /* advanced_testcase */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class mod_myplugin_some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

PHPUnit integration

2014-06-18T23:47:42Z

Skodak: /* basic_testcase */

Moodle PHPUnit integration was created to simplify using of PHPUnit framework in Moodle. It consists of specialised bootstrap script, utility scripts that initialise testing environment and highly optimised custom test case classes that handle automatic global state resetting after test that includes global variables, database rollback and purging of dataroot. We also try to bridge the gap between the design and coding style of Moodle and PHPUnit.

Most of the documentation at http://www.phpunit.de/manual/3.6/en/index.html is relevant to Moodle PHPUnit integration, exceptions and additions are described bellow.

=Definitions=
These definitions may differ in each testing framework or programming language. The definitions here should be valid for PHPUnit framework with our Moodle tweaks.

;Test suite: is a collection of test cases or other suites usually related to one area of the product. It is defined in PHPUnit configuration files (phpunit.xml by default).

;Test file: is a file with *_test.php name which contains a test case. (*_Test.php in PHPUnit)

;Test case: is a class with test methods. Moodle tests extend basic_testcase or advanced_testcase. (PHPUnit_Framework_TestCase in PHPUnit)

;Test: is a public method starting with "test_" prefix defined in test case class. It is the implementation of the test procedure.

;Assertion: is the actual comparison of expected and actual behaviour of the tested code.

=Organisation of test files=
All testing related files are stored in <code>/tests/</code> subdirectories:

* <code>.../tests/*_test.php</code> are PHPUnit test files
* <code>.../tests/fixtures/</code> contains auxiliary files used in tests
* <code>.../tests/performance/</code> is reserved for performance testing scripts
* <code>.../tests/other/</code> is used for everything else that does not fit

=basic_testcase=
''basic_testcase'' is useful for simple tests that do not modify database or global variables. If something accidentally changes global state the test fails. This test case class is nearly identical to PHPUnit_Framework_TestCase used in PHPUnit documentation.

<code php>
<?php

class mod_myplugin_sample_basic_testcase extends basic_testcase {
public function test_equals() {
$a = 1 + 2;
$this->assertEquals(3, $a);
}
}
</code>

There are no extra methods that could be used in tests

=advanced_testcase=
By default each test starts with fresh new moodle installation. Test may modify database content, files or global variables. It is possible to use data generators to create new course, categories, module instances and other objects, alternatively table data can be preloaded from XML or CSV files.

<code php>
<?php

class some_permission_testcase extends advanced_testcase {
public function test_isadmin() {
global $DB;

$this->resetAfterTest(true); // reset all changes automatically after this test

$this->assertFalse(is_siteadmin()); // by default no user is logged-in
$this->setUser(2); // switch $USER
$this->assertTrue(is_siteadmin()); // admin is logged-in now

$DB->delete_records('user', array()); // lets do something crazy

$this->resetAllData(); // that was not a good idea, let's go back
$this->assertTrue($admin = $DB->record_exists('user', array('id'=>2)));
$this->assertFalse(is_siteadmin());
}
}
</code>

==Extra methods==
; resetAfterTest(bool) : true means reset automatically after test, false means keep changes to next test method, default null means detect changes
; resetAllData() : reset global state in the middle of a test
; setAdminUser() : set current $USER as admin
; setGuestUser() : set current $USER as guest
; setUser() : set current $USER to a specific user - use getDataGenerator() to create one
; getDataGenerator() : returns data generator instance - use if you need to add new courses, users, etc.
; preventResetByRollback() : terminates active transactions, useful only when test contains own database transaction handling
; createXXXDataSet() : creates in memory structure of database table contents, used in loadDataSet() (eg: createXMLDataSet(), createCsvDataSet(), createFlatXMLDataSet())
; loadDataSet() : bulk loading of table contents
; getDebuggingMessages() : Return debugging messages from the current test. (Moodle 2.4 and upwards)
; resetDebugging() : Clear all previous debugging messages in current test. (Moodle 2.4 and upwards)
; assertDebuggingCalled() : Assert that exactly debugging was just called once. (Moodle 2.4 and upwards)
; assertDebuggingNotCalled() : Assert no debugging happened. (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing sending of messages|redirectMessages()]]: Captures ongoing messages for later testing (Moodle 2.4 and upwards)
; [[Writing PHPUnit tests#Testing_sending_of_emails|redirectEmails()]]: Captures ongoing emails for later testing (Moodle 2.6 and upwards)

==Restrictions==
* it is not possible to modify database structure such as create new table or drop columns from advanced_testcase.

=Moodle specific features=
* detection of global state changes - helps with detection of unintended changes in database
* highly optimised global state reset
* dataset loading - this feature is copied from PHPUnit database testcases
* automatic generation of phpunit.xml - init script builds list of plugin testcases
* database driver testing class - used for functional DB tests
* SimpleTest emulation class - helps with migration of old tests
* debugging() interception - enables to control and test any expected debug output. (Moodle 2.4 and upwards)

=Limitations=
* no Selenium support
* no support for PHPUnit_Extensions_Database_TestCase - it is possible to use data set loader only

=See also=
* [[Writing PHPUnit tests]]

[[Category:Unit testing]]

Writing PHPUnit tests

2014-06-18T23:45:04Z

Skodak: /* Sample plugin testcase */

{{Moodle 2.3}}

Moodle PHPUnit integration is designed to allow easy adding of new tests. At the start of each test the state is automatically reset to fresh new installation (unless explicitly told not to reset).

=Testcase classes=

There are two basic test class that are supposed to used in all Moodle unit tests - basic_testcase and advanced_testcase. '''Please note it is strongly recommended to put only one testcase into each class file.'''
;basic_testcase : Very simple tests that do not modify database, dataroot or any PHP globals. It can be used for example when trying examples from the official PHPUnit tutorial.
;advanced_testcase : Enhanced testcase class enhanced for easy testing of Moodle code.

There is a third testcase class that is specially designed for testing of our Moodle database layer, it should not be used for other purposes.

== Assertions ==

The complete list of assertions can be found in the [http://www.phpunit.de/manual/3.7/en/appendixes.assertions.html phpunit manual].
==Sample plugin testcase==

PHPUnit tests are located in <code>tests/*_test.php</code> files in your plugin, for example mod/myplugin/tests/sample_test.php, the file should contain only one class that extends <code>advanced_testcase</code>:

<code php>
class mod_myplugin_sample_testcase extends advanced_testcase {
public function test_adding() {
$this->assertEquals(2, 1+2);
}
}
</code>

==Inclusion of Moodle library files==

If you want to include some Moodle library files you should always declare '''global $CFG'''. The reason is that testcase files may be included from non-moodle code which does not make the global $CFG available automatically.

==Automatic state reset==
By default after each test Moodle database and dataroot is automatically reset to the original state which was present right after installation. make sure to use $this->resetAfterTest() to indicate that the database or changes of standard global variables are expected.

<code php>
class mod_myplugin_testcase extends advanced_testcase {
public function test_deleting() {
global $DB;
$this->resetAfterTest(true);
$DB->delete_records('user');
$this->assertEmpty($DB->get_records('user'));
}
public function test_user_table_was_reset() {
global $DB;
$this->assertEquals(2, $DB->count_records('user', array()));
}
}
</code>

=Generators=

Tests that need to modify default installation may use generators to create new courses, users, etc. All examples on this page should be used from test methods of a test class derived from advanced_testcase.

Note if you are using PHPUnit @dataProvider functions to provide parameters to unit tests, you can not use the data generator or change the user etc in the data provider function.

==Creating users==
At the start of each test there are only two users present - guest and administrator. If you need to add more test accounts use:
<code php>
$user = $this->getDataGenerator()->create_user();
</code>

You may also specify properties of the user account, for example:
<code php>
$user1 = $this->getDataGenerator()->create_user(array('email'=>'user1@example.com', 'username'=>'user1'));
</code>

By default no user is logged-in, use setUser() method to change current $USER value:
<code php>
$this->setUser($user1);
</code>

Guest and admin accounts have a shortcut methods:
<code php>
$this->setGuestUser();
$this->setAdminUser();
</code>

Null can be used to set current user back to not-logged-in:
<code php>
$this->setUser(null);
</code>

==Creating course categories==

<code php>
$category1 = $this->getDataGenerator()->create_category();
$category2 = $this->getDataGenerator()->create_category(array('name'=>'Some subcategory', 'parent'=>$category1->id));
</code>

==Creating courses==

<code php>
$course1 = $this->getDataGenerator()->create_course();

$category = $this->getDataGenerator()->create_category();
$course2 = $this->getDataGenerator()->create_course(array('name'=>'Some course', 'category'=>$category->id));
</code>

==Creating activities==

Some activity plugins include instance generators. The generator class are defined in plugindirectory/tests/generator/lib.php.

Example of creation of new course with one page resource:

<code php>
$course = $this->getDataGenerator()->create_course();
$generator = $this->getDataGenerator()->get_plugin_generator('mod_page');
$generator->create_instance(array('course'=>$course->id));
</code>

==Creating cohorts==
{{Moodle 2.4}}
Since 2.4 there the data generator supports creation of new cohorts.

<code php>
$cohort = $this->getDataGenerator()->create_cohort();
</code>

==Simplified user enrolments==
{{Moodle 2.4}}
Instead of standard enrolment API it is possible to use simplified method in data generator. It is intended to be used with self and manual enrolment plugins.

<code php>
$this->getDataGenerator()->enrol_user($userid, $courseid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid);
$this->getDataGenerator()->enrol_user($userid, $courseid, $teacherroleid, 'manual');
</code>

==Other types of plugin==
{{Moodle 2.5}}
Any other type of plugin can have a generator. The generator class should extend component_generator_base, and then you can get an instance using $mygenerator = $this->getDataGenerator()->get_plugin_generator($frankenstylecomponentname);

For some types of plugin, like mod documented above, there may be a more specific class than component_generator_base to extend, like testing_module_generator. That will give a consistent set of method names to use. Otherwise, you can create whatever methods you like on your generator, to create the different things you need to work whith.

=Long tests=

All standard test should execute as fast as possible. Tests that take a loner time to execute (>10s) or are otherwise expensive (such as querying external servers that might be flooded by all dev machines) should be execute only when PHPUNIT_LONGTEST is true. This constant can be set in phpunit.xml or directly in config.php.

=Large test data=
See advanced_testcase::createXMLDataSet() and advanced_testcase::createCsvDataSet() and related functions there for easier ways to manage large test data sets within files rather than arrays in code. See [[PHPUnit_integration#Extra_methods]]

=Testing sending of messages=
{{Moodle 2.4}}
You can temporarily redirect all messages sent via message_send() to a message sink object. This allows developers to verify that the tested code is sending expected messages.

To test code using messaging first disable the use of transactions and then redirect the messaging into a new message sink, you can inspect the results later.
<code php>
$this->preventResetByRollback();
$sink = $this->redirectMessages();
//... code that is sending messages
$messages = $sink->get_messages();
$this->assertEquals(3, count($messages));
//.. test messages were generated in correct order with appropriate content
</code>

=Testing sending of emails=
{{Moodle 2.6}}
You can temporarily redirect emails sent via email_to_user() to a email message sink object. This allows developers to verify that the tested code is sending expected emails.

To test code using messaging first unset 'noemailever' setting and then redirect the emails into a new message sink where you can inspect the results later.
<code php>
unset_config('noemailever');
$sink = $this->redirectEmails();
//... code that is sending email
$messages = $sink->get_messages();
$this->assertEquals(1, count($messages));
</code>

=Extra test settings=

Usually the test should not interact with any external systems and it should work the same on all systems. But sometimes you need to specify some option for connection to external systems or system configuration. It is intentionally not possible to use $CFG settings from config.php.

There are several ways how to inject your custom settings:
* define test setting constants in your phpunit.xml file
* define test setting constants in your config.php

These constants may be then used in your test or plugin code.

=See also=
* [[PHPUnit integration]]
* [[PHPUnit]]

[[Category:Unit testing]]

PHPUnit

2014-06-18T23:42:05Z

Skodak: /* Using the @group annotation */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class qtype_stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

[[Category:Unit testing]]

PHPUnit

2014-06-18T23:41:22Z

Skodak: /* Using the @group annotation */

{{Moodle 2.3}}

=What is PHPUnit=
PHPUnit by Sebastian Bergmann is an advanced unit testing framework for PHP. It is installed as Composer dependency and is not part of Moodle installation. To run PHPUnit tests, you have to manually install it on your development computer or test server.

Read the excellent guide at
* [http://phpunit.de/manual/current/en/index.html PHPUnit Manual]

=Installation of PHPUnit via Composer=

The installation procedure depends on your operating system.
* Install Composer dependency manager

cd /your/moodle/dirroot
curl -s https://getcomposer.org/installer | php

On Windows go to https://getcomposer.org/download/ and download the Composer-Setup.exe file

* Execute Composer installer

cd /your/moodle/dirroot
php composer.phar install --dev

(If that gives you connection problems try...)

php composer.phar install --dev --prefer-source

Troubleshooting:
* On Windows if you are behind a proxy you will need to setup an environment variable called HTTP_PROXY with a value detailing your HTTP Proxy address and port before composer will correctly download files.
* You may be prompted for github credentials when installing composer dependencies.
** This is used to generate an personal access token to avoid being rate limited by github.
** If you have Two Factor Authentication enabled on your github account, or do not wish to supply your own credentials you will need to generate a token manually:
*** Visit https://github.com/settings/applications and request personal access token
*** Copy this token and add it to your [https://gist.github.com/andrewnicols/c5377ed25a9df1006ce1 ~/.composer/config.json]
** ( See [https://github.com/composer/composer/issues/2280 composer issue #2280] for further details of this bug.)

Detailed instructions:
* [http://getcomposer.org/doc/00-intro.md Composer documentation]

Detailed instructions:
* [[PHPUnit installation in Windows]]
* [[PHPUnit installation in OS X]]

== Uninstalling previous PEAR based version ==

Before using composer, this page used to suggest to install phpunit via PEAR. If you did so, you may wish to uninstall that package now. This should work:

$ pear uninstall phpunit/DbUnit
$ pear uninstall phpunit/PHPUnit

=Initialisation of test environment=

Our PHPUnit integration requires a dedicated database and dataroot. First, add a new dataroot directory and prefix into your config.php, you can find examples in config-dist.php (scroll down to 'Section 9').

$CFG->phpunit_prefix = 'phpu_';
$CFG->phpunit_dataroot = '/home/example/phpu_moodledata';

If your system does not have a direct connection to the Internet, you also need to specify your proxy in config.php - even though you normally specify it by using the admin settings user interface. (If you do not use a proxy, you can skip this step.) Check the settings on the relevant admin settings page, or from the mdl_config table in your database, if you are unsure of the correct values.

// Normal proxy settings
$CFG->proxyhost = 'wwwcache.example.org';
$CFG->proxyport = 80;
$CFG->proxytype = 'HTTP';
$CFG->proxybypass = 'localhost, 127.0.0.1, .example.org';
// Omit the next lines if your proxy doesn't need a username/password:
$CFG->proxyuser = 'systemusername';
$CFG->proxypassword = 'systempassword';

Then you need to initialise the test environment using following command.

cd /home/example/moodle
php admin/tool/phpunit/cli/init.php

This command has to be repeated after any upgrade, plugin (un)installation or if you have added tests to a plugin you are developing:

'''NOTE:''' make sure that your php cli executable (or the one you want to use) is correctly on your path as the individual init scripts will call it repeatedly.

=Test execution=

To execute all test suites from main configuration file execute the <code>vendor/bin/phpunit</code> script from your <code>$CFG->dirroot</code> directory.

cd /home/example/moodle
vendor/bin/phpunit

The rest of examples uses <code>phpunit</code>, please substitute it with <code>vendor/bin/phpunit</code> or create a shortcut in your dirroot.

In IDEs, you may need to specify the path to the PHPUnit configuration file. Use the absolute path to <code>phpunit.xml</code> from your <code>$CFG->dirroot</code>.

There is an alternative script for running of tests via web interface: <code>admin/tool/phpunit/webrunner.php</code>. Use this as the last resort only when you cannot use the command-line interface on your test server. It will most probably break due to permissions problems if you try to execute it both from command-line and from webrunner. This feature is not officially supported.

===How to run only some tests===

==== Running a single test quickly ====

The fastest way to run a single test is:

vendor/bin/phpunit my_test_class_name my/tests/filename.php

This is faster than other methods because it avoids the need to search for the test file, but you should be careful because it may be possible to run tests this way which are not included in the normal run. If you use this method, do at least one full test run (or --group run, as below) to ensure the test can be found.

==== Using the @group annotation ====

If you add annotations like

<code php>
/**
* Unit tests for {@link stack_cas_keyval}.
* @group qtype_stack
*/
class stack_cas_keyval_exception_testcase extends basic_testcase {
</code>

to all the classes in your plugin, then you can run just the tests for your plugin by doing

phpunit --group qtype_stack

Therefore, it is suggested that you annotate all your tests with the Frankenstyle name of your plugin.

==== Using multiple phpunit.xml files ====

It's easy to create alternative phpunit.xml files defining which tests must be run together. For reference, take a look to the default /phpunit.xml available in your base directory once the testing environment has been initialised. After creating the custom file you will be able to run those tests with

vendor/bin/phpunit -c path/to/your/alternative/phpunit/file.xml

Also, for commodity, you can use this command:

php admin/tool/phpunit/cli/util.php --buildcomponentconfigs

It will, automatically, create one valid phpunit.xml file within each component (plugin or subsystem) and other important directories, so later you will be able to execute tests like

vendor/bin/phpunit -c mod/forum[/phpunit.xml] // Note that it's not needed to specify the name of the file (if it is 'phpunit.xml').
vendor/bin/phpunit -c question
vendor/bin/phpunit -c question/type/calculated
vendor/bin/phpunit -c backup
vendor/bin/phpunit -c lib/dml
...

or, also

cd directory/with/phpunit.xml
phpunit

=External test resources=
{{Moodle 2.6}}
By default Moodle phpunit tests contact http://download.moodle.org server when testing curl related functionality. Optionally you may checkout a local copy of the test scripts and access it instead:

# clone https://github.com/moodlehq/moodle-exttests to web directory
# add to your config.php or modify phpunit.xml file <code php>define('TEST_EXTERNAL_FILES_HTTP_URL', 'http://localhost/moodle-exttests');</code>

=Writing new tests=
* read [http://www.phpunit.de/manual/current/en/ official PHPUnit online documentation]
* see [[Writing PHPUnit tests]]

=Conversion of existing SimpleTests=
* see [[SimpleTest conversion]]

=PHPUnit support in IDEs=

* [http://www.phpsrc.org/projects/pti-phpunit/wiki/ Eclipse PHP Tool Integration]
* [http://blog.jetbrains.com/webide/2009/12/phpunit-support/ PHPStorm IDE]
* [http://netbeans.org/kb/docs/php/phpunit.html Netbeans]

=Common Unit Test Problems=
[[Common unit test problems]]

=Performance=

A typical run of full PHPUnit tests for Moodle 2.7 takes 10-20 minutes depending on the machine. If tests run slowly for you:

* Ensure you are using a database and filesystem running on the same machine that is running the tests (not on a remote server).
* Apply developer-only performance settings to your database: [[Postgres Tuning For Developers]]

[[Category:Unit testing]]

Setting up PhpStorm

2014-06-18T23:35:56Z

Skodak: /* Database editor */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===
Install latest Java JDK 1.7.x from [http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html Oracle] (Java 1.6 from Apple is not maintained much).

You can hack older PhpStorm 7 to be compatible with Java 1.7 by editing the "PhpStorm.app/Contents/Info.plist" file, set JVMOptions - JVMVersion = 1.7*

==General settings==

* Disable missing @throws tag warning in "Preferences / Project Settings / Inspections / PHP / PHPDoc"
* Strip trailing whitespace from "Modified Lines" in "Preferences / IDE Settings / Editor"
* Show line numbers in "Preferences / IDE Settings / Editor / Appearance"

==Code formatting==

* Setup coding style to use all rules from [Coding style] in "Preferences / Project Settings / Code Style / PHP".
* Set line separator to Unix in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Moodle code checker==
TODO

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
# Click on the "Database" tab to see the database window
# Click "+" in the top left and add "Database source" for your database
# Note: click on the link to download the necessary drivers directly from IDE

Setting up PhpStorm

2014-06-18T23:16:42Z

Skodak: /* PHPUnit integration */

[http://www.jetbrains.com/phpstorm/ PhpStorm] is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc.

==Installation==

===OS X===
Install latest Java JDK 1.7.x from [http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html Oracle] (Java 1.6 from Apple is not maintained much).

You can hack older PhpStorm 7 to be compatible with Java 1.7 by editing the "PhpStorm.app/Contents/Info.plist" file, set JVMOptions - JVMVersion = 1.7*

==General settings==

* Disable missing @throws tag warning in "Preferences / Project Settings / Inspections / PHP / PHPDoc"
* Strip trailing whitespace from "Modified Lines" in "Preferences / IDE Settings / Editor"
* Show line numbers in "Preferences / IDE Settings / Editor / Appearance"

==Code formatting==

* Setup coding style to use all rules from [Coding style] in "Preferences / Project Settings / Code Style / PHP".
* Set line separator to Unix in "Preferences / Project Settings / Code Style / General".
* Set right margin to 132 or 180 in "Preferences / Project Settings / Code Style / General".

==Moodle code checker==
TODO

==PHPUnit integration==
# Install [[PHPUnit]] via Composer
# Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled.
# Go to "Run / Edit configurations"
# Add PHPUnit configuration by clicking on "+"
# Click "Use alternative configuration file" and select your phpunit.xml file
# Go to "Run / Run ..." and select your new PHPUnit configuration to run

==Database editor==
TODO