Integrate with Plesk Service Plans

Plesk SDK API gives you the ability to integrate with Plesk service plans by adding and checking custom permissions and limits to service plans, resellers and subscriptions, and also by registering extension-related plan items in Plesk.

Adding and checking custom permissions and limits

Two following hooks are used:

• pm_Hook_Permissions - for managing permissions.
• pm_Hook_Limits - for managing limits.

Permissions and limits have string IDs like “manage_git” and “max_repos”. These IDs must be unique for individual extensions, but the same ID name can be used in different extensions. IDs are stored with native permissions, limits, and other plan items’ data in the Plesk database, in the TmplData table. To prevent IDs from clashing, we add an extension name prefix to each ID. For example, the “git” extension adds custom limit named “max_repos”, so within the Plesk context it becomes “git_max_repos”, but in the extension code “max_repos” is used.

Note

ID names can contain only numbers, letters, and the underscore symbol. All other symbols are not allowed.

A new class Service Plan wrapper (pm_Plan) was added. Objects are constructed by service plan ID. There are getters: getId() and getName().

The methods hasPermission($name) and getLimit($name) provide access to custom permissions and limits, correspondingly. These methods are available for domains (pm_Domain) and service plans (pm_Plan).

The method pm_Client::hasPermission($name, $domain) checks if the client has access to the domain’s functionality restricted by permission.

Examples

Permissions

To set a permission, specify the following parameters:

• key - a unique key to access the permission (for example, ‘manage_git’).
• default - the permission’s default value (“true” or “false”).
• place - the column in which the permission will be placed. Takes either self::PLACE_MAIN (the left column) or self::PLACE_ADDITIONAL (the right/hideable column). The parameter is optional, PLACE_MAIN is used by default.
• name - the permission’s display name. It is recommended to use localization for the name.
• description - a short description. It is recommended to use localization for the description.
• master - a master permission key (optional). A dependent permission can be switched on only if the master permission is switched on. Note that the master permission must be also declared by the extension.

Add a hook (filename: Permissions.php) with the following code:

class Modules_ServicePlanApi_Permissions extends pm_Hook_Permissions
{
    public function getPermissions()
    {
        return [
            'manage_mypermission' => [
                'default' => true,
                'place' => self::PLACE_ADDITIONAL,
                'name' => 'My Permission',
                'description' => 'My Permission description.',
            ],
            'manage_mydependentpermission' => [
                'default' => false,
                'place' => self::PLACE_ADDITIONAL,
                'name' => 'My Dependent Permission',
                'description' => 'My Dependent Permission description.',
                'master' => 'manage_mypermission',
            ],
        ];
    }
}

Usage example (checking permission):

class IndexController extends pm_Controller_Action
{
    public function init()
    {
        parent::init();

        /** @var pm_Domain */
        $domain = $this->_getDomain(); // get pm_Domain somehow
        if (!$domain->hasPermission('manage_something')) {
            throw new pm_Exception($this->lmsg('permissionDenied'));
        }

        if (!pm_Session::getClient()->hasPermission('manage_something', $domain)) {
            throw new pm_Exception($this->lmsg('permissionDenied'));
        }
    }

    // Some code here
}

Limits

To set a limit, specify the following parameters:

• key - a unique key to access the limit (for example, ‘max_repos’).
• default - the limit’s default value (type: integer, set -1 for “unlimited”).
• place - the column in which the limit will be placed. Takes either self::PLACE_MAIN (the left column) or self::PLACE_ADDITIONAL (the right/hideable column). The parameter is optional, PLACE_MAIN is used by default.
• name - the limit’s display name. It is recommended to use localization for the name.
• description - a short description. It is recommended to use localization for the description.

Add a hook (filename: Limits.php) with the following code:

class Modules_ServicePlanApi_Limits extends pm_Hook_Limits
{
    public function getLimits()
    {
        return [
            'max_limit' => [
                'default' => -1,
                'place' => self::PLACE_MAIN,
                'name' => 'My Limit',
                'description' => 'My Limit description.',
            ],
        ];
    }
}

Usage example (checking limit):

class IndexController extends pm_Controller_Action
{
    // Some code here

    public function addAction()
    {
        $repoCount = $this->_getRepoCount(); // get actual amount of limited entity
        /** @var pm_Domain */
        $domain = $this->_getDomain(); // get pm_Domain somehow
        $limit = $domain->getLimit('max_repos');
        if ($limit > -1 && $limit <= $repoCount) {
            throw new pm_Exception($this->lmsg('maxRepoCountCreated'));
        }
        // Some code here
    }

    // Some code here
}

You can find a sample extension illustrating this concept here.

Registering extension-related plan items in Plesk

You can create service plans associated with your extension and add subscriptions based on those plans. This can be useful for implementing pay-as-you-go payment schemes. To register plan items, your extension should implement the pm_Hook_PlanItems class, name it Modules_<Extension name>_PlanItems, and place it in the plib/hooks/ directory. Together with the plan items, this hook defines whether the plan items should be exclusive (the default behavior), or whether several plan items could be included in a single subscription.

Registered plan items would be created in Plesk when the extension is installed and removed from Plesk when the extension is removed. When the extension is upgraded, the plan items would be updated (new ones would be added, previously created ones would be updated or deleted if they are no longer registered in the hook).

To get the list of extension plan items that are included in a Plesk service or subscription, use the following methods that return an array of plan item keys:

• pm_Plan::getPlanItems()
• pm_Domain::getPlanItems()

Examples

An example of plan items registry (PRODUCT_ROOT_D/admin/plib/modules/example/hooks/PlanItems.php):

class Modules_Example_PlanItems extends pm_Hook_PlanItems
{
    public function getPlanItems()
    {
        return [
            'starter' => 'Starter',
            'lite' => 'Lite',
            'premium' => 'Premium'
        ];
    }
}

An example of plan items being retrieved:

$plan = new pm_Plan(3);
$plan->getPlanItems(); // ['starter']
$domain = new pm_Domain(1);
$domain->getPlanItems(); // []

You can find a sample extension illustrating this concept here.