Developer Area/Events API

Mahara has a simple Event Subscription API that lets plugins respond to actions performed throughout the system.

1. Core code triggers an event by calling handle_event('eventtype', $data);
2. A table of event subscriptions is called. Each subscription specifies a plugin, and a function to be called should that event occur.
3. Each event subscription function is called. 'eventtype', and $data are passed to it.

Subscribing to an Event

To subscribe your Plugin to an event type, override the public static function "get_event_subscription()" in your Plugin subclass. Your function should return an array of event subscription objects. Each event subscription object should be a generic object containing three fields:

• plugin: The name of the plugin
• event: The name of the event you want to subscribe to
• callfunction: The (public static) function in the plugin's Plugin subclass, which should be called when the event occurs.

Example:

The blog core plugin subscribes to the createuser event, in order to create a default Journal for each newly created user. Here's what the subscription-related code looks like in artefact/blog/lib.php:

class PluginArtefactBlog extends PluginArtefact { 

    public static function get_event_subscriptions() {
        $sub = new stdClass();
        $sub->plugin = 'blog';
        $sub->event = 'createuser';
        $sub->callfunction = 'create_default_blog';
        return array($sub);
    }

    public static function create_default_blog($event, $user) {
        $name = display_name($user, null, true);
        $blog = new ArtefactTypeBlog(0, (object) array(
            'title'       => get_string('defaultblogtitle', 'artefact.blog', $name),
            'owner'       => $user['id'],
        ));
        $blog->commit();
    }
}

In core code

Core event subscriptions are inserted directly into the event_subscription table, by the core_install_firstcoredata_defaults() function in htdocs/lib/upgrade.php (on installation), and by the xmldb_core_upgrade() function in htdocs/lib/db/upgrade.php (on upgrade)

Triggering an event

Triggering an event is easy. You simply call:

handle_event(
    $eventtype,
    $data
);

• eventtype is a string with the name of the event type
• $data is an object containing data that subscribers to the event type will want

It's up to the author of each new event type to decide what data should be passed to that event's subscribers. Unfortunately Mahara currently has no central place to document this data. Your best bet is simply to search the source code for the name of the event type, and see what the code is passing in.

Supported event types

The legal event types are stored in the database table event_type. As of Mahara 1.7, the following event types are supported:

• createuser
• updateuser
• suspenduser
• unsuspenduser
• deleteuser
• undeleteuser
• expireuser
• unexpireuser
• deactivateuser
• activateuser
• userjoinsgroup
• saveartefact
• deleteartefact
• deleteartefacts
• saveview
• deleteview
• blockinstancecommit
• addfriend
• removefriend
• addfriendrequest
• removefriendrequest
• creategroup
• loginas

To play well with existing code, your code should trigger one of these events if it does the related action.