Plesk SDK API gives you the ability to execute long tasks and display their progress in the Plesk UI. To launch a long task and track it afterwards, create a long task class that extends pm_LongTask_Task and define its run() method. It is also possible to customize the behavior of a long task by overriding the onStart(), onError(), and onDone() methods that do nothing by default.

While implementing the run() method, you may need to get some information about the task via getters (getInstanceId(), getParam(), getParams(), getStatus(), and getProgress()), and update information about the task via setters (setParam(), setParams(), and updateProgress()). Any scalar data types & arrays are accepted as task parameters. Objects cannot be task parameters.

Long task execution is presented in the Plesk UI by default. The statusMessage() method is responsible for displaying the message that appears in the task progress bar. Long task progress can be either trackable or not (by default, it is not trackable). If you would like to make task progress trackable, the value of the $trackProgress property must be set to “true”, and task progress can be updated via the updateProgress() method during task execution. If the task should not be displayed in the Plesk UI at all, the $hidden property must be set to “true”.

The getId() method defines the task identifier. It is obtained from the task class name by excluding the prefix & the module name (for example, Modules_Example_Task_Create => task_create; PleskExtExampleTaskCreate => taskcreate; TaskCreate => taskcreate). Feel free to redefine it and use it for getting the task queue.

As soon as the long task class is implemented, the long task must be registered in Plesk. A class named Modules_<Extension name>_LongTasks must be derived from pm_Hook_LongTasks and placed in the plib/hooks/ directory.

Finally, the pm_LongTask_Manager class can be used for launching long tasks, canceling them, and getting the task queue. Note that a task can be executed either:

• Within domain context - visible only within the context of the specifed domain, or when there is no active domain (for example, in service provider view).
• With no context - visible only when there is no active domain (for example, in service provider view).

All extension tasks will be deleted on extension removal.

Examples

An example of a task with trackable progress (PRODUCT_ROOT_D . /admin/plib/modules/example/library/Task/Create.php):

class Modules_Example_Task_Create extends pm_LongTask_Task
{
    public $trackProgress = true;

    public function run()
    {
        sleep(2);
        $this->updateProgress(30);
        sleep(2);
        $this->updateProgress(60);
        sleep(2);
        $this->updateProgress(90);
        sleep(2);
    }

    public function statusMessage()
    {
        switch ($this->getStatus()) {
            case static::STATUS_RUNNING:
                return pm_Locale::lmsg('running');
            case static::STATUS_DONE:
                return pm_Locale::lmsg('done', ['id' => $this->getId()]);
        }
        return '';
    }

    public function onStart()
    {
        $this->setParam('onStart', 1);
    }

    public function onDone()
    {
        $this->setParam('onDone', 1);
    }
}

An example of a task registry (PRODUCT_ROOT_D . /admin/plib/modules/example/hooks/LongTasks.php):

class Modules_Example_LongTasks extends pm_Hook_LongTasks
{
    public function getLongTasks()
    {
        return [new Modules_Example_Task_Create()];
    }
}

An example of task management:

$taskManager = new pm_LongTask_Manager();

$task1 = new Modules_Example_Task_Create();
$task1->setParam('counter', 15); //set task param
$taskManager->start($task1); // start task

$task2 = new Modules_Example_Task_Create();
$task2 = $taskManager->start($task2, new pm_Domain(1)); // start task in context of domain #1

$tasks = $taskManager->getTasks(['task_create']); // get tasks with no context, $task1
$tasks = $taskManager->getTasks(['task_create'], [new pm_Domain(1)]); // get tasks with domain #1 context, $task1, $task2

$taskManager->cancel($task1); // cancel $task1 execution and delete it
$taskManager->cancelAllTasks(); // cancel all extension tasks execution and delete them