Plugin API documentation - Relation between plugin status and actions

  • i-MSCP Plugin API - Relation Between Plugin Status And Actions (Revision 0.0.22 - Plugin Api 0.2.6)


    Introduction


    This document describe the relations between the plugin status and the actions which are run by the i-MSCP plugin manager. This is a draft, which is still opened for comments.


    The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in this document are to be interpreted as described in RFC 2119.


    Plugin status and actions


    Plugin status


    Plugin status are represented by two fields in the plugin table of the i-MSCP database, which are:

    • The plugin_status field, which reflect the current status of the plugin
    • The plugin_error field, which allow the plugin manager to be aware about any error that occurred during the execution of a specific action


    Theses fields are managed by the i-MSCP plugin manager. A plugin SHOULD NOT handle these fields by itself.


    When an action is run and if all goes fine, the plugin_status field is set to the next status (see below), However, when an action is stopped by a listener which listen an event that is triggered in the context of the action, the plugin_status field is set back to its initial state.


    On error, the plugin_error field is set with the last error message and the plugin_status field is left untouched. This give a chance to re-run the action, once the problem is fixed.


    In normal context, the plugin_error field is set to NULL.


    Plugin actions


    A plugin action is not simply represented by a plugin method. For the plugin manager, a plugin action is represented by a couple of events, plugin methods and/or subactions, which are triggered/run when a specific action is run (such as when the admin activates a specific plugin through the plugin interface).


    A subaction is nothing more than an action, which is run through another action.


    Plugin method


    A plugin method is only run if implemented. Any plugin method MUST be idempotent. This mean essentially that if a method is run several time, the final result must be same. For example, even if an uninstall() method is run several time, the subsequent calls must not fail only because a package has been already uninstalled.


    toinstall status / install action


    The toinstall status correspond to the install action. Next status should be enabled.


    This action is run for plugins which are being installed. When this action is run, the following events, plugin methods and subactions are triggered/run:


    FronTend

    • The onBeforeInstallPlugin event
    • The install() plugin method, which is responsible to do any installation task
    • The onAfterInstallPlugin event
    • The enable subaction


    Backend (Only if the plugin provide a backend)

    • The onBeforeInstallPlugin event
    • The install() plugin method, which is responsible to do any installation task
    • The onAfterInstallPlugin event
    • The enable subaction


    Important


    Any plugin which is installable MUST implement the install() method in its main class (PHP side), even if that method do nothing. This allows the plugin manager to know when a plugin is installable or not.


    Only plugins which have their status set to uninstalled (initial state) can be installed.


    toenable status / enable action


    The toenable status correspond to the enable action. Next status should be enabled.


    This action is run for plugins which are being enabled (activated). When this action is run, the following events and plugin methods are triggered/run:


    FronTend

    • The onBeforeEnablePlugin event
    • The enable() plugin method, which is responsible to do any activation task
    • The onAfterEnablePlugin event


    Backend (Only if the plugin provide a backend)

    • The onBeforeEnablePlugin event
    • The enable() plugin method, which is responsible to do any activation task
    • The onAfterEnablePlugin event


    Important


    Only plugins which have their status set to disabled can be enabled.


    Action switch

    • In case where a new plugin version is available, the plugin manager triggers the update action instead
    • In case plugin configuration change is needed, the plugin manager triggers the change action instead

    Note: the update action has precedence over the change action. For this reason, the update action must handle configuration changes too.


    todisable status / disable action


    The todisable status correspond to the disable action. Next status should be disabled.


    This action is run for plugins which are being disabled (deactivated). When this action is run, the following events and plugin methods are triggered/run:


    FronTend

    • The onBeforeDisablePlugin event
    • The disable() plugin method, which is responsible to do any deactivation task
    • The onAfterDisablePlugin event


    Backend (Only if the plugin provide a backend)

    • The onBeforeDisablePlugin event
    • The disable() plugin method, which is responsible to do any deactivation task
    • The onAfterDisablePlugin event


    Important


    Only plugins which have their status set to enabled can be disabled.


    tochange status / change action


    The tochange status correspond to the change action. Next status should be enabled.


    This action is run for enabled (activated) plugins, each time i-MSCP gets updated, or when the plugin configuration has been changed. When this action is run, the following events, plugin methods and subactions are triggered/run:


    FronTend

    • The disable subaction
    • The enable subaction


    Backend (Only if the plugin provide a backend)

    • The disable subaction
    • The onBeforeChangePlugin event
    • The change() plugin method, which is responsible to do any change task
    • The onAfterChangePlugin event
    • The enable subaction


    Important


    This action acts in two contexts:

    • When i-MSCP is being updated
    • When a change in plugin configuration has been detected


    In the first context, the action is run only on the backend, while in the second context, the action is run on both side, the frontEnd and the backend.


    You must note that if you want change the configuration of a specific plugin, you MUST ensure first that it is already enabled. Any change done in a plugin configuration file will be stored in the database only if the plugin is already enabled, and once you'll have updated the plugin list. This behavior is by design.


    Only plugins which have their status set to enabled can be changed.


    toupdate status / update action


    The toupdate status correspond to the update action. Next status should be enabled.


    This action is run for enabled (activated) plugins, for which an update is available. When this action is run, the following events, plugin methods and subactions are triggered/run:


    FronTend

    • The disable subaction
    • The onBeforeUpdatePlugin event
    • The update() plugin method, which is responsible to do any update task
    • The onAfterUpdatePlugin event
    • The enable subaction


    Backend (Only if the plugin provide a backend)

    • The disable subaction
    • The onBeforeUpdatePlugin event
    • The update() plugin method, which is responsible to do any update task
    • The onAfterUpdatePlugin event
    • The enable subaction


    update() plugin method parameters


    When this method is run, it receive two parameters which are in order:

    • The current version of the plugin
    • The version to which the plugin is updated


    Important


    Only plugins which have their status set to enabled can be updated.


    enabled status / run action


    The enabled status correspond to the run action. Next status should be enabled.


    This action is run for enabled (activated) plugins, each time a backend request is made. When this action is run, the following events and plugin methods are triggered/run:


    Backend (Only if the plugin provide a backend)

    • The onBeforeRunPlugin event
    • The run() method, which is responsible to run the plugin logic
    • The onAfterRunPlugin event


    Important


    Because the run action is run on every backend request without any constraint, you must pay attention to not bind all your plugin logic on it. For instance, if you have a plugin which provides statistical graphs, you MUST NOT rely only on that action to build the graphs. Instead, you SHOULD either register a cron task, or provide some datum (through plugin item) allowing your plugin to know when it should build new graphs.


    Return value from the run action is ignored by default because it's the responsibility of the plugins to set error status for their items. In case a plugin doesn't manage any item, you MAY force the plugin manager to not ignore the return value by defining the FORCE_RETVAL attribute in the init() method of the plugin and set it value to yes.


    Only plugins which have their status set to enabled can be run.


    touninstall status / uninstall action


    The touninstall status correspond to the uninstall action. Next status should be uninstalled.


    This action is run on plugins which are being uninstalled. When this action is run, the following events and plugin methods are triggered/run:


    Frontend

    • The onBeforeUninstallPlugin event
    • The uninstall() plugin method, which is responsible to do any uninstallation task
    • The onAfterUninstallPlugin event


    Backend (Only if the plugin provide a backend)

    • The onBeforeUninstallPlugin event
    • The uninstall() plugin method, which is responsible to do any uninstallation task
    • The onAfterUninstallPlugin event


    Important


    Any plugin which can be uninstalled MUST implement the uninstall() method in its main class (PHP side), even if that method do nothing. This allows the plugin manager to know when a plugin can be uninstalled or not.


    Only plugins which have their status set to disabled (initial state) can be uninstalled.


    todelete status / delete action


    The todelete status correspond to the delete action.


    This action is triggered on plugins which are being deleted. When this action is run, the following events and plugin methods are triggered/run:


    Frontend

    • The onBeforeDeletePlugin event
    • The delete() plugin method, which is responsible to do any deletion task
    • The onAfterDeletePlugin event


    Important


    This action delete the plugin from the database and file system.


    Only plugins which have their status set to disabled or uninstalled (initial state) can be deleted.


    other status


    This module will not handle any other status than those described above. Any other status MUST be considered as corrupted.


    It's important to understand that all status described above belong to the plugins themselves, and not to their own items. In case where a plugin handle its own items it's its responsibility to handle their status.


    install, update and enable actions


    When these actions are run, the backend part of the plugin is installed from the plugin package into the imscp/engine/Plugins directory, which is the plugins backend repository. The file is searched in a specific sub directory of plugin package:


    Code
    1. <PluginName>/backend/<PluginName>.pm


    uninstall and disable actions


    When these actions are run, the backend part of the plugin is removed from the backend plugins repository.


    Plugin error


    On error, the backend part of the plugin is removed from the backend plugins repository.

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().

  • Yes, it is understandable. :)


    Thank you for the overview.
    Now I also have a better understanding of how the various actions are related to each other.


    Could you please post and pin that somewhere here in the forum, where everybody could read it.

    Patched i-MSCP 1.5.4 on Debian Stretch | Apache 2.4.52 | Nginx 1.21.4 | OpenSSL 1.1.1 | php 7.0 - 8.1 | Dovecot 2.3.17.1 | Bind 9.16.25 | Postfix 3.1.15 | MariaDB 10.1.48 | ProFTPD 1.3.5b | Rspamd 2.7 | ClamAV 0.103.4 | Roundcube 1.5.2 | CrowdSec 1.3.0

    Edited once, last by Nuxwin ().


  • Yes, it is understandable. :)


    Thank you for the overview.
    Now I also have a better understanding of how the various actions are related to each other.


    Could you please post and pin that somewhere here in the forum, where everybody could read it.


    Split Done ;)

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().


  • Maybe we should add a Sektion Development in Wiki and add such things


    Sure. I've not the time ATM to move that documentation to the wiki so feel free. :) It's only a small part of the final (dev) documentation for the plugins there. The basis explanations, skeletons and so on are still on my todo list. I must also provide a documentation for the frontEnd side (plugin manager) and describe each action which are triggered, with their specific contexts.

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().

  • Hello;


    TheCry
    mrpink


    The toupdate status stanza has been updated. This is take in consideration the changes I'll made today to fix the issue for which we have talked in our internal forum.


    To resume, you'll no longer have to embed the activation logic into the update() method. Once the changes will be in our repository, I'll update your OpenDKIM plugin. Then, after, you'll be able to do same for all your plugins.


    Thanks you. ;)

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().

  • Updated again. Added introduction.

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().

  • Updated (revision 0.0.5)

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().

  • Updated to revision 0.0.6 (a lot of change). FronTend actions which are run and events which are triggered were added.

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206

    Edited once, last by Nuxwin ().

  • Updated (Revision 0.0.14)

    badge.php?id=1239063037&bid=2518&key=1747635596&format=png&z=547451206