Subscribe to Plesk Events

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

In this chapter:

handleEvent Method

Object Types and Actions

Old and New Values Combinations

Old and New Values Description

Add Custom Events

 

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.