Add Custom Events

Plesk SDK API allows you to add custom events, log them in the Action Log, and assign event handlers via Plesk and the SDK API in extensions.

Custom events can be added by an ActionLog hook which extends the pm_Hook_ActionLog class and is located at hooks/ActionLog.php. The public method getEvents() should return the key value array. Where keys are unique (for this extension), event ids and values are localized to the event title. To avoid ids clashing, we add the 'ext_my-extension_' prefix to each event id. To handle such an event via the SDK API, the id with the prefix should be used. For example, your extension name is 'my-extension' and the event id (in the hook) is 'smth_created'. You need to catch the action with the name 'ext_my-extension_smth_created' in the event listener class.

A new class pm_ActionLog was added to provide the ability to fire events (method pm_ActionLog::submit()). It takes a number of arguments:

  • actionId (required) - an unique event id like it was specified in the hook.
  • objectId (optional) - a parameter to pass the object id for context (type: integer).
  • oldValue (optional) - a parameter for context to expose some changes.
  • newValue (optional) - a parameter for context to expose some changes.

Event handlers can also be added in Plesk (Tools & Settings => Event Manager).

These event handlers are stored in the extension's settings (pm_Settings) in JSON format. The event handlers are removed automatically on extension removal.

Examples

Add a custom event by hook

class Modules_MyExtension_ActionLog extends pm_Hook_ActionLog
{
    public function getEvents()
    {
        return [
            'smth_created' => 'Something created',
        ];
    }
}

Submit ActionLog event

/* Method in your controller */
public function addAction()
{
    $form = new AddSmthForm(['context' => [
        // pass some vars to context
    ]]);
 
    if ($this->getRequest()->isPost() && $form->isValid($this->getRequest()->getPost())) {
        $status = 'success';
        $message = 'OK';
        try {
            $objectId = $form->processForm(); // Assume that form processing returns newly created object id
 
            // Submit action log event here
            pm_ActionLog::submit('smth_created', $objectId, 'old value', 'new value');
 
        } catch (pm_Exception $e) {
            $status = 'error';
            $message = $e->getMessage();
        }
        $this->_redirectWithStatus($status, $message, $this->getRedirectUrl());
    }
    $this->view->form = $form;
}

Handle an event via the SDK API

class Modules_MyExtension_EventListener implements EventListener
{
    public function handleEvent($objectType, $objectId, $action, $oldValue, $newValue)
    {
        if ($action == 'ext_myextension_smth_created') {
            pm_Log::info('Handle event: ext_myextension_smth_created');
            pm_Log::info('Object Id: ' . var_export($objectId, true));
            pm_Log::info('Old value: ' . var_export($oldValue, true));
            pm_Log::info('New value: ' . var_export($newValue, true));
        }
    }
}
 
return new Modules_MyExtension_EventListener();
 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.