Naming events

The general naming pattern is something_changed, when reading the name of event it may be sometimes easier to pronounce as "something was changed" or "something has changed". For updates the something it is usually the table that is being modified, it gets a bit more tricky when viewing complex tables. Some examples of "somethings":

report
comment
user
program
tag
course
entry
page
role
post
position
course_module

If you are referring to an object inside another object, just use the most specific one. E.g. 'note' not 'feedback_note'.

The verb at the end of event should be ideally standardised. Some common choices are:

viewed
updated
deleted
created
submitted
uploaded
started
sent

Object table and id

Either both or none should be defined, the object table must be a real database table and the object id must be id from that database table.

Levels

There are three basic educational levels - other, teaching and participating. See the moodle description here:

https://docs.moodle.org/dev/Event_2#Level_property

We need to decide the rules for Totara, typically anything outside of a course would be OTHER.

Unit testing

Unit tests for events are mandatory in upstream Moodle, the reasons are:

test backwards compatibility of old events and logging via assertEventLegacyLogData() and assertEventLegacyData() - usually the original parameters are copy/pasted directly to unit tests
prevention of future regressions - the most important part is to test other property structure to prevent BC problems in the future
detect incorrect use of snapshots and context instance via assertEventContextNotUsed()
test create_from_ methods if present
if possible test code that triggers the code (if action abstracted in some library)

To test if an event got triggered in your code you can use the event redirecting functionality provided by our advanced testcase:

public function test_if_the_correct_event_got_triggered() {
    // After that all events will land in the sink and won't be triggered as usual
    $sink = $this->redirectEvents();

	// Run your tests
	...

    // Now you can get all events triggered since redirecting was turned on
	// and can test if the expected events got triggered 
    $events = $sink->get_events();
	// You can clear the sink, this does not stop the redirecting
	$sink->clear();
	// Or you can stop the redirecting completely
	$sink->close();
}

create_from_xx pattern

PHP does not allow overriding of methods with different number of parameters, this mean that new factory methods for events need to use separate methods. The standard pattern is to use

event::create_from_something(some_class $something, $extradata)->trigger()

helper methods.

Benefits:

it is easier to trigger the event
it is easier to review the event
it is possible to prevent access to create() which prevents typos and incorrect data being passed to constructor especially when event is trigger is several places
it is much easier to write unit tests
create_from_ methods are the best documentation when writing event observers

Inline docs

It is mandatory to include description of other parameter. If create_from_ is not used all other parameters should be described too.

Bulk events

Bulk events are strongly discouraged. If they are defined it must be done before the introduction of related individual events because plugins must observe both bulk and individual events.

Sometimes it may be useful to trigger start and end events for bulk actions so that observers may temporarily stop watching individual events for performance reasons, the processing is done in bulk when the original bulk event ends.

Upstream changes

Do not change upstream Moodle events. If we need more events in upstream code we should probably create them in totora_core.

There will be some exceptions - such as cohorts/audiences because we have modified the database tables. Or completion which should be ideally upstreamed.

Error logging

The new event system was designed to allow logging of things that changed or happened, the error or exception mean that something did not happen. there are no error events in upstream Moodle. Ideally we should have a different way to notify admins about problems that require their attention. System log is for now the best place to log and look for errors.

Public developer documentation

Events