App event handlers

Contents...

Handlers can be used by your app to execute additional actions on events triggered during other apps' operation.

A simple example of a handler is an additional function called when a contact is deleted. If your app is subscribed to the contact deletion event, i.e. contains a corresponding event handler, then every attempt to delete a contact in Contacts app will allow your app to execute some extra checkup or update its own data related to the contact being deleted.

Events in other apps' source code, which can be processed by your custom app, are triggered by means of method wa()->event(array('app_id', 'event_id')).

Each event handler must be described in a separate file. App event handler files must be located in your app's subdirectory lib/handlers/. The name of a handler file must have the form [external_app_id].[event_id].handler.php, where [external_app_id] must be replaced with the external app ID whose event must be processed, and [event_id] – with that of the event being processed.

For example, the file of a handler of the contact deletion event triggered by Contacts app must be available at lib/handlers/contacts.delete.handler.php. This file must contain a PHP class named by the template [app_id][External_app_id][Event_id]Handler extending system class waEventHandler.

Example of a handler class file:

<?php

class myappContactsDeleteHandler extends waEventHandler
{
    public function execute(&$params)
    {
        // your custom event processing logic
    }
}

The main method of the event handler class must be execute() which may accept parameters passed to method wa()->event().

Handler debugging

When debugging your custom event handler, keep in mind that any exceptions registered during the execution of a handler are suppressed by the framework. Information about any such suppressed exceptions are logged to file wa-log/error.log.