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();