Extensions can obtain complete information and control over Plesk entities (customer accounts, service plans, and so on) via the XML API interface. This interface assumes exchanging operation requests wrapped into XML-structured packets. Plesk receives such an XML-structured operation request, processes it, and responds with a PHP class which fields mimic the XML tree structure. The structure of the XML packets is defined by the XML API protocol (refer to the XML API Guide).

Every Plesk server supports a number of versions of XML API (for backward compatibility). It is possible to send packets of a particular XML API version by explicitly providing the protocol version. If you do not specify the version, the most recent supported XML API version will be used.

To perform an operation via XML API, use the pm_ApiRpc class. The used methods are:

Additionally, Plesk provides a PHP library that simplifies working with XML API. This library can be used as an alternative or complementing the method described here. See section Using XML API PHP Library below for instructions on adding and using the library in your extension.

Example 1: Getting information on a subscription (XML API protocol specified)

To perform an operation of getting information on a subscription via XML API with a specified protocol version, use the code:

$request = <<<APICALL
<webspace>
  <get>
    <filter>
      <id>170</id>
    </filter>
    <dataset>
      <gen_info/>
    </dataset>
  </get>
</webspace>
APICALL;

$response = pm_ApiRpc::getService('1.6.3.3')->call($request);
echo 'Domain name: ' . $response->webspace->get->result->data->gen_info->name;

 The PHP library allows to achieve the same goal using this code:

$client = new \PleskX\Api\InternalClient();

echo 'Domain name: ' . $client->webspace()->get('id', 170)->name;

The following sample project is provided by Plesk to illustrate the use of XML API PHP library: https://github.com/plesk/ext-php-api-lib-demo.

Example 2: Getting server statistic (XML API protocol unspecified)

Here is an example of an XML API call with an unspecified protocol version.

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

The PHP library allows to achieve the same goal using this code:

$stats = $client->server()->getStatistics()->objects;

Example 3: Turning on PHP settings for a subscription (administrator rights required)

By default, the API calls are performed under the privileges of the current user. However, sometimes the actions require the administrative privileges. In such cases, the $login argument of the call() method should be used.

For example, let’s look at an extension that turns on PHP settings for a subscription. The extension sends the following request:

$request = <<<APICALL
<webspace>
  <set>
    <filter>
      <id>2</id>
    </filter>
    <values>
      <php-settings>
        <setting>
          <name>extension</name>
          <value>msql.so</value>
        </setting>
      </php-settings>
    </values>
  </set>
</webspace>
APICALL;

To perform this request, you need administrator’s rights:

$response = pm_ApiRpc::getService()->call($request, 'admin');

Error Handling

If you run an XML API call with data which is not a valid XML tree, a PHP warning will be generated.

If an XML packet is not a valid operation call, the system will throw the PleskAPIParseException exception.

Using XML API PHP Library

  1. Add the library to your extension

    Edit composer.json to require plesk/api-php-lib

    Example: https://github.com/plesk/ext-php-api-lib-demo/blob/master/composer.json#L7

  2. Create instance of client

    $client = new \PleskX\Api\InternalClient();

    Example: https://github.com/plesk/ext-php-api-lib-demo/blob/master/src/plib/controllers/IndexController.php#L10

  3. Use the necessary API calls using client

    $client->...

The following sample project is provided by Plesk to illustrate the use of XML API PHP library: https://github.com/plesk/ext-php-api-lib-demo.