Event Handlers

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 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/sw-cp-server/error_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

 

Leave your comments on this page

Leave your feedback or question on this documentation topic below. For technical assistance, contact your hosting service provider or submit a request to Plesk support. Suggest new features for Plesk here. Discuss general questions on the Plesk forum. All offtopic comments will be removed.