The event handlers interface lets you subscribe to a particular Plesk event and trigger a particular action depending on the event information. For example, if you need to create a DNS zone each time a new domain is created, use event handlers.

For triggering simple actions, such as logging information about Plesk events, we recommend that you use the event tracking mechanism available in the Plesk UI. To learn how to use this mechanism, refer to the Administrator’s Guide, section Event Tracking.

For complicated actions, Plesk provides another, more flexible, mechanism of event tracking. This mechanism allows running PHP scripts upon Plesk events. In this section, we will explain in detail how to use it.

How to Create a Handler

Event handlers examine the Plesk action log and invoke the handleEvent method each time an action is added to the log. Thus, event handler cannot prevent the action. If an attempt to perform the action fails, Plesk does not issue notifications through this mechanism.

Event handlers for the same event can be triggered in an arbitrary order.

To add an event handler, create a .php file in the following directory:

• On Linux: /usr/local/psa/admin/plib/registry/EventListener

• On Windows: %plesk_dir%admin\plib\registry\EventListener

  Where %plesk_dir% stands for the full path to the directory where Plesk is installed.

This file must contain a class which implements the handleEvent method of the EventListener interface. The code must create an instance of this class and return it. For example:

<?php
class TestEventListener implements EventListener
{
    public function handleEvent($objectType, $objectId, $action, $oldValues, $newValues)
    {
        // TODO: add implementation here...
    }
}
return new TestEventListener();
?>

Read more about the handleEvent parameters in the handleEvent method. The complete listings of available object types, actions, and value arrays are available in corresponding subsections of this section.

Adding Event Handlers to Extensions

If you have an extension and want it to trigger certain actions upon Plesk events, add an event handler to your extension. Assume that your extension’s ID is my-extension.

To add an event handler to the extension:

1. Create a .php file with the content described above.
2. Change the class name to Modules_MyExtension_EventListener. For more information about assigning names to classes within your extension, refer to Class Naming Conventions.
3. Change the file’s name to EventListener.php.
4. Place the file to /plib/library/ inside the extension directory.

Handling Selected Events Only

Normally, the event handlers are responsible for handling only a limited set of events. It is, therefore, recommended to explicitly list the specific events that are to be processed, by means of the filterActions() method. The following example defines an event handler and specifies that it is only to be executed when the ‘phys_hosting_delete’ event occurs.

<?php
class Modules_MyExtension_EventListener implements EventListener
{
    public function filterActions()
    {
        return [
            'phys_hosting_delete',
        ];
    }

    public function handleEvent($objectType, $objectId, $action, $oldValues, $newValues)
    {
        switch ($action) {
            case 'phys_hosting_delete' :
               // delete by $objectId or $oldValues
                break;
        }
    }
}

return new Modules_MyExtension_EventListener();
?>

If the filterActions() method is not defined, or it returns an empty array, the event handler will receive and process all the events, which will slow down the system.

Debugging a Handler Code

To debug the handleEvent method, you can use the following code:

<?php
class TestEventListener implements EventListener
{
    public function handleEvent($objectType, $objectId, $action, $oldValues, $newValues)
    {
            error_log('inside TestEventListener::handleEvent');
    }
}
return new TestEventListener();
?>

After an event occurs, this handler will be invoked.

The output will be available in the following files:

• On Linux: /var/log/plesk/panel.log
• On Windows: %plesk_dir%admin\logs\php_error.log