Developer Area/Events API

Mahara has a simple Event Subscription API that lets plugins respond to actions performed throughout the system. When hookable events happen in core code, the code triggers an "event". Plugins can "subscribe" to these events, providing an "event handler" function that will be called when an event is triggered.

It's a simple version of the Publish-subscribe pattern.

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 callers are 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.