Exercise 3. Plesk Entities and Authentication

This exercise will guide you through creating an extension that reports the number of customer accounts, websites, databases, and mail accounts on a Plesk server; the output format will be a plain text or the text in XML or JSON. While writing the extension, you will learn how to do the following:

• Use custom authentication (call PHP files bypassing controllers).
• Access Plesk entities through XML API.

We assume that the extension ID is plesk-stats, and that you start with the code inside the ex3 directory. This code is partly written by us to help you focus only on certain areas. Additionally, we have populated the directory with media content necessary for the exercise. To see the completed exercise, examine the ex2complete directory.

Step 1. Set up custom authentication.

The extension we are going to write will consist of the form which the administrators will use to set up the data output format, and the endpoint form where users will request the statistics. As the statistics is secure data, we should set up access control to deliver the results only to certain users. The two ways on how to do this are possible:

• Determine the user type - administrator, reseller, or customer and restrict access basing on this type. This is accomplished by creating the pm_Session class instance and using its boolean methods isClient(), isReseller(), isAdmin().

  $session = new pm_Session();

  $client = $session->getClient();

  if ($client->isAdmin()) {

  }

• Write your own authentication method.

As we assume that the statistics web service will be used by third-party applications, we will write a custom authentication method.

Start with defining a secret token authToken in our post-installation script and saving it to the key-value storage. For this, append the following two lines to /plib/scripts/post-install.php:

pm_Settings::set('useAuth', true);
pm_Settings::set('authToken', md5(uniqid(rand(), true)));

If you are new to installation scripts and working with key-values storage, we recommend that you read Exercise 2.

Next, add a form that defines the output method. Nothing new here, we have already explained how to do it by writing appropriate controllers, actions, and views in Exercise 1, so we have added all the necessary code for you. If you are curious, see the following files:

/htdocs/index.php

/plib/controllers/IndexController.php

/plib/library/Form/Settings.php

/plib/views/scripts/index/index.phtml

One thing about the form worth noting here: Among other fields, the form includes links to the statistics. These links navigate to /public/?authToken=$authToken under the extension's web root directory. The web /public is associated with the /htdocs/public directory of an extension. This is a special directory. If someone requests a resource from this directory, the control will be passed directly to the resource bypassing controllers. In our example, if we want to have a public endpoint, we need to create a script inside this directory and tell the service consumers the script URL.

To control the statistics requests to /public, add the following lines to /htdocs/public/index.php:

if (pm_Settings::get('useAuth') && @$_GET['authToken'] != pm_Settings::get('authToken')) {
    die('Invalid auth token supplied.');
}

The code compares the token from the storage and the token in request. If they do not match, the script execution is stopped.

Great, now you have the authentication system, let's add some statistics to the /htdocs/public/index.php output.

Step 2. Retrieve information about Plesk entities.

The extension will use the Modules_PanelStats_Reporter class to communicate with XML API. The class is already defined it requires only an XML API call. Open /plib/library/Reporter.php and change the class constructor to request the required statistics:

$request = '<server><get><stat/></get></server>';
$this->_stats = pm_ApiRpc::getService()->call($request)->server->get->result->stat->objects;

The description of the operation the code requests is available here.

The response description is available here.

According to the manual, the _stats class field contains the nodes described here.

The pre-written methods of Modules_PanelStats_Reporter facilitate processing of the response data. The getResultsXml method returns the data as an XML tree, the getResultsJson returns the result in the JSON format, and getResultsPlain returns the information in the plain text. Now we need to provide this information to the extension users.

Step 3. Provide the statistics to the extension users.

As discussed at step 1, end users will request /htdocs/public/index.php for the statistics, and this file currently has the access control implemented. To provide the statistics, change the file so that it looks as follows:

<?php

require_once('sdk.php');

pm_Context::init('plesk-stats');

if (pm_Settings::get('useAuth') && @$_GET['authToken'] != pm_Settings::get('authToken')) {
    die('Invalid auth token supplied.');
}

$reporter = new Modules_PanelStats_Reporter();

$format = isset($_GET['format']) ? $_GET['format'] : 'xml';

if ('plain' == $format) {
    echo $reporter->getResultsPlain();
} else if ('json' == $format) {
    header("Content-Type: application/json");
    echo $reporter->getResultsJson();
} else {
    header("Content-Type: text/xml");
    echo $reporter->getResultsXml();
}

Comparing to the previous version of the file, this version creates the Modules_PanelStats_Reporter instance and provides the statistics depending on the format GET argument.

You may have noticed that the code starts with the following line:

require_once('sdk.php');

Important: This line is required to set up classes auto-loading in this script, as the auto-loading feature does not work in /htdocs/public by default.

Step 4. Install and test the extension.

Congratulations! You have completed the exercise. To install your extension to Plesk:

1. Add the contents of the ex3 directory (not the directory itself) to a ZIP archive using your favorite software.

   Important: Ensure that meta.xml resides in the root of the unpacked archive. This is a very important requirement, otherwise Plesk will return an error on adding your extension to Plesk.

2. Log in to Plesk as the administrator and add the extension on the Server Management > Extensions page.

You should see your extension in the list, set up the extension settings and follow the links in the form to see Plesk statistics in different formats.